Tsctl command line reference

From embeddedTS Manuals

The tsctl client provides access to the tsctl API functions via the tsctl command line. There is a one to one correspondence between the C API and the command line parameters and output as described in the tsctl API Conventions.

System

ClassCount

Obtain the number of classes defined by the server. The value returned is one greater than the maximum value allowed to be passed as the class parameter in any tsctl protocol request to the server.

Request

[@host] System[:instance] ClassCount

Reply

ClassCount

Examples:

m4200x8200# tsctl System ClassCount
System_ClassCount_0=11

InstanceCount

Obtain the number of instances of the specified class which are available on the server for clients to make requests for through the tsctl protocol. The value returned is one greater than the maximum value allowed to be passed as the instance parameter in any tsctl protocol request to the specified class; if a value equal or greater is passed, the server will signal an exception by closing the connection to the client.

If the server does not have any instances of the specified class, the value returned will be 0.

Request

[@host] System[:instance] InstanceCount ClassNumber

Reply

InstanceCount

Examples:

m4200x8200# tsctl System InstanceCount 1
System_InstanceCount_0=14

APICount

This function returns the number of API functions implemented in the specified class . The value returned is one greater than the maximum value allowed to be passed as the instance parameter in any tsctl protocol request to the specified class; if a value equal or greater is passed, the server will signal an exception by closing the connection to the client.

If the server does not have any instances of the specified class, the value returned will be 0.

Request

[@host] System[:instance] APICount ClassNumber

Reply

APICount

Examples:

m4200x8200# tsctl System APICount 1
System_APICount_0=34

LockCount

This function returns the total number of system locks on the server. This value only has meaning if the server was compiled with threading support.

Request

[@host] System[:instance] LockCount

Reply

LockCount

LockHolderInfo

This function returns an Array of LockHolderInfo structures, one element for each lock currently held.

The structures are filled in such that the nth element will contain information about the nth lock. The pid field contains the process id (on the server) servicing the connection that holds the lock. The count field contains the number of times the given process has acquired the lock. If this value is zero, then the value of the pid field should be ignored, as the lock is not held.

This function is not useful outside the context of a server, as stand-alone applications do not typically implement the support necessary.

typedef struct LockHolderInfo {
  int pid;
  int count;
} LockHolderInfo;


Request

[@host] System[:instance] LockHolderInfo

Reply

LockHolderInfo

ConnWaitInfo

This function returns an Array of information about each connection and what lock it is waiting for.

It does not make sense to use this function outside the context of the tsctl server.

typedef struct ConnectionWaitInfo {
   int pid;
   int wait; // lock waited for, or -1 if none
} ConnectionWaitInfo;

Request

[@host] System[:instance] ConnWaitInfo

Reply

ConnWaitInfo

CANBusGet

This function returns the number of the Bus instance used by the specified CAN instance to access the CAN registers. If the given instance does not have an underlying Bus instance, or if the specified CAN instance does not exist, then a negative value is returned.

Request

[@host] System[:instance] CANBusGet CANInstance

Reply

CANBusGet

Examples:

m4500x8200# tsctl System CANBusGet 0
System_CANBusGet_0=7

BuildTime

This function returns the time at which the binary containing libtsctl and currently being invoked was compiled, expressed in seconds since the beginning of the Unix Epoch.

Request

[@host] System[:instance] BuildTime

Reply

BuildTime

Examples:

m4200x8200# tsctl System BuildTime
System_BuildTime_0=1352302469
m4200x8200# date -d @`tsctl "Mode;Dec;NoAssign;;System BuildTime"`
Wed Nov  7 15:34:29 UTC 2012

ModelId

This function returns the Model ID of the board on which the server is running, in hexadecimal. For instance, 0x4200 corresponds to the TS-4200.

Request

[@host] System[:instance] ModelId

Reply

ModelId

Examples:

m4200x8200# tsctl Mode Hex \; System ModelId
System_ModelId_0=0x00004200

BaseBoardId

This function returns the ID of the base board on which the server is running, in hexadecimal. For instance, 0x8160 corresponds to the TS-8160. If no base board is detected, 0 is returned;

Request

[@host] System[:instance] BaseBoardId

Reply

BaseBoardId

Examples:

m4200x8200# tsctl Mode Hex \; System BaseBoardId
System_BaseBoardId_0=0x00008200

MapLength

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function returns the number of string to value mappings.

Request

[@host] System[:instance] MapLength

Reply

MapLength

Examples:

m4200x8200# tsctl System MapLength
System_MapLength_0=458

MapGet

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function returns the nth string in the string to value mapping as a newly allocated Array. It also places the nth value in the array passed.

Request

[@host] System[:instance] MapGet MapIndex

Reply

MapGet

Examples:

m4200x8200# tsctl System MapGet 0
System_MapGet_0="AIO"
System_MapGet_0_Value=9

MapLookup

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function returns the value of the specified string in the mapping. For the purpose of this look up case is ignored in both the String parameter and in the table entries. Returns a negative value if the specified string does not exist in the mapping.

Request

[@host] System[:instance] MapLookup String

Reply

MapLookup

Examples:

m4200x8200# tsctl System MapLookup DIO_39
System_MapLookup_0=-1

MapLookupPartial

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function finds the first string in the mapping that begins with the specified string, and has the specified value, and returns the remainder of the string. If a match is not found, returns an empty strings. In either case, the returned value is newly allocated.

Request

[@host] System[:instance] MapLookupPartial StringPrefix Value

Reply

MapLookupPartial

Examples:

m4200x8200# tsctl System MapLookupPartial attrib.Connector.Name. 1 
System_MapLookupPartial_0="CN1_"

MapAdd

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function adds the specified string:value mapping to the system mapping table. If the given string already has it value in the mapping it will be replaced by the new value. A positive values is returned on success. The string str is internally copied, so the caller is responsible for freeing it as needed.

Note: When invoked in direct mode (i.e. with no host argument and no tsctl server running locally) the System Map does not persist after the current invocation of tsctl and so any additions to the default Map will be lost.

Request

[@host] System[:instance] MapAdd String Value

Reply

MapAdd

Examples:

m4200x8200# tsctl System \; MapAdd LASER_CTRL 77 \; MapLookup LASER_CTRL
System_MapAdd_0=SystemSuccess
System_MapLookup_0=77

MapDelete

The System object provides a "Map" which associates string names to integer values. This is used to store DIO names, attributes, and other information. This information is automatically populated by reading /etc/dioctl.config at startup.

This function removes the specified string from the mapping. Returns a positive value on success, or a negative value if there is no such string to delete.

Note: When invoked in direct mode (i.e. with no host argument and no tsctl server running locally) the System Map does not persist after the current invocation of tsctl.

Request

[@host] System[:instance] MapDelete String

Reply

MapDelete

Examples:

m4200x8200# tsctl System \; MapAdd LASER_CTRL 77 \; MapDelete LASER_CTRL
System_MapAdd_0=SystemSuccess
System_MapDelete_0=SystemSuccess

Note

tsctlSystemNoteDesc Coming Soon!

Request

[@host] System[:instance] Note Message

Reply

Note

Examples:Coming Soon!

Version

This function returns a string containing the release version that the libtsctl binary is based on. As of version 0.91 this number replaces the old release number based on year, month, day, hour, and minute. If you make any modifications to libtsctl or any supplied sample applications you are strongly urged to create a unique version scheme to distinguish your fork from the official Technologic Systems customer source code release. This can be accomplished by passing -DLIBTSCTL_ORGANIZATION="yourname" to the compiler when building the part of your application containing libtsctl.

Request

[@host] System[:instance] Version

Reply

Version

Examples: Coming Soon!

UptimeServer

This function returns the number of seconds since the libtsctl being invoked was first initialized by means of any class being initialized via the appropriate Init call (e.g. BusInit(n) for the Bus class). For tsctl, this is done during startup of the server, or startup of the client when invoking the command in direct mode.

Request

[@host] System[:instance] UptimeServer

Reply

UptimeServer

Examples:

m4200x8200# tsctl System UptimeServer
System_UptimeServer_0=1

UptimeHost

This function returns the number of seconds since the host machine running the libtsctl based binary was last booted.

Request

[@host] System[:instance] UptimeHost

Reply

UptimeHost

Examples:

m4200x8200# tsctl System UptimeHost
System_UptimeHost_0=3778841

FPGARevision

This function returns the FPGA revision number. This eliminates the need to know board specific differences in how this value is obtained.

Request

[@host] System[:instance] FPGARevision

Reply

FPGARevision

Examples:

m4200x8200# tsctl System FPGARevision
System_FPGARevision_0=4

EchoNumber

This function returns the number that was passed. This is mainly for test purposes. For instance, the tsctl client will automatically perform lookups on strings passed where numbers were expected; this function can be used to see what the lookup is returning without actually using it for anything.

This differs from calling the System MapLookup function because the tsctl client supports adding lookups with the "+" character. Therefore you can determine the final result even with non-trivial lookups.

Request

[@host] System[:instance] EchoNumber n

Reply

EchoNumber

Examples:

m4500x8200# tsctl System EchoNumber FLAG_EXT_ID
System_EchoNumber_0=32
m4500x8200# tsctl System EchoNumber EXT
System_EchoNumber_0=0
m4500x8200# tsctl System EchoNumber FLAG_EXT_ID+FLAG_RTR
System_EchoNumber_0=48

Bus

Lock

This function acquires or releases the Bus resource lock. The lock must be held before any other functions on the given Bus are called.

The num parameter is unused and should be set to 0.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the Bus lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] Bus[:instance] Lock num flags

Reply

Lock

Examples: Coming Soon!

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.


enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] Bus[:instance] Unlock num flags

Reply

Unlock

Examples: Coming Soon!

Preempt

tsctlBusPreemptDesc Coming Soon!

Request

[@host] Bus[:instance] Preempt

Reply

Preempt

Examples: Coming Soon!

Peek8

This function performs an 8-bit read of the bus at the specified Address, and returns the value read.

Request

[@host] Bus[:instance] Peek8 Address

Reply

Peek8

Examples: Coming Soon!

Poke8

This function performs an 8-bit write of the bus at the specified Address, with the specified Value.

Request

[@host] Bus[:instance] Poke8 Address Value

Reply

Examples: Coming Soon!

Peek16

This function performs a 16-bit read of the bus at the specified Address, and returns the value read.

Request

[@host] Bus[:instance] Peek16 Address

Reply

Peek16

Examples: Coming Soon!

Poke16

This function performs a 16-bit write to the bus at the specified Address, with the specified Value.

Request

[@host] Bus[:instance] Poke16 Address Value

Reply

Examples: Coming Soon!

Peek32

This function performs a 32-bit read of the bus at the specified Address, and returns the value read.

Request

[@host] Bus[:instance] Peek32 Address

Reply

Peek32

Examples: Coming Soon!

Poke32

This function performs a 32-bit write to the bus at the specified Address, with the specified Value.

Request

[@host] Bus[:instance] Poke32 Address Value

Reply

Examples: Coming Soon!

BitGet8

This function performs an 8-bit read of the bus at the specified Address, and returns 1 if the if the specified bit in the value read is set, or 0 if the bit is cleared.

The bit parameter must be in the range of 0 (lsb) to 7 (msb).

Request

[@host] Bus[:instance] BitGet8 Address BitNumber

Reply

BitGet8

Examples: Coming Soon!

BitAssign8

This function performs an 8-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the specified bit Value, which must be 1 or 0.

The bit parameter must be in the range of 0 to 7.

Request

[@host] Bus[:instance] BitAssign8 Address BitNumber Value

Reply

Examples: Coming Soon!

BitSet8

This function performs an 8-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the a value of 1.

The bit parameter must be in the range of 0 to 7.

Request

[@host] Bus[:instance] BitSet8 Address BitNumber

Reply

Examples: Coming Soon!

BitClear8

This function performs an 8-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the a value of 0.

The bit parameter must be in the range of 0 to 7.

Request

[@host] Bus[:instance] BitClear8 Address BitNumber

Reply

Examples: Coming Soon!

BitGet16

This function performs a 16-bit read of the bus at the specified Address, and returns 1 if the if the specified BitNumber in the value read is set, or 0 if the bit is cleared.

The bit parameter must be in the range of 0 to 15.

Request

[@host] Bus[:instance] BitGet16 Address BitNumber

Reply

BitGet16

Examples: Coming Soon!

BitAssign16

This function performs a 16-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the specified bit Value, which must be 1 or 0.

The bit parameter must be in the range of 0 to 15.

Request

[@host] Bus[:instance] BitAssign16 Address BitNumber Value

Reply

Examples: Coming Soon!

BitSet16

This function performs a 16-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the a value of 1.

The bit parameter must be in the range of 0 to 15.

Request

[@host] Bus[:instance] BitSet16 Address BitNumber

Reply

Examples: Coming Soon!

BitClear16

This function performs a 16-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the a value of 0.

The bit parameter must be in the range of 0 to 15.

Request

[@host] Bus[:instance] BitClear16 Address BitNumber

Reply

Examples: Coming Soon!

BitGet32

This function performs a 32-bit read of the bus as the specified Address, and returns 1 if the if the specified bit in the value read is set, or 0 if the bit is cleared.

The bit parameter must be in the range of 0 to 31.

Request

[@host] Bus[:instance] BitGet32 Address BitNumber

Reply

BitGet32

Examples: Coming Soon!

BitAssign32

This function performs a 32-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the specified bit Value, which must be 1 or 0.

The bit parameter must be in the range of 0 to 31.

Request

[@host] Bus[:instance] BitAssign32 Address BitNumber Value

Reply

Examples: Coming Soon!

BitSet32

This function performs a 32-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the value of 1.

The bit parameter must be in the range of 0 to 31.

Request

[@host] Bus[:instance] BitSet32 Address BitNumber

Reply

Examples: Coming Soon!

BitClear32

This function performs a 32-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the value of 0.

The bit parameter must be in the range of 0 to 31.

Request

[@host] Bus[:instance] BitClear32 Address BitNumber

Reply

Examples: Coming Soon!

PeekStream

This function performs a read burst on the bus. A typical bus will have a native bus size that it performs these reads with. Note that some busses may not support a read burst.

The address parameter specifies the starting address of the burst.

The direction parameter specifies the increment to add (or, for a negative value, to subtract) from the address for each subsequent element. Not all implementations may support this paramter.

The burst is read into the specified dest buffer Array. The number of bytes read will be equal to the length of the Array upon entry.

Request

[@host] Bus[:instance] PeekStream address direction dest.Length

Reply

Examples: Coming Soon!

PokeStream

This function performs a write burst on the bus. A typical bus will have a native bus size that it performs these writes with. Note that some busses may not support a write burst.

The address parameter specifies the starting address of the burst.

The direction parameter specifies the increment to add (or, for a negative value, to subtract) from the address for each subsequent element. Not all implementations may support this paramter.

The burst is read from the specified data buffer. The number of bytes written to the bus from the buffer is equal to the Array length of data.

Request

[@host] Bus[:instance] PokeStream address direction data

Reply

Examples: Coming Soon!

Refresh

Some busses support atomic reading and writing segments of its data. A bus that supports this operation will implement the Refresh function to atomically read those segments that support this function.

One example of a bus that does this is CacheBus. This bus supports caching portions of a (presumably slow) bus backed by hardware registers.

Refresh should always be called before Commit.

Request

[@host] Bus[:instance] Refresh

Reply

Examples: Coming Soon!

Commit

Some busses support atomic reading and writing segments of its data. A bus that supports this operation will implement the Commit function to atomically write those segments that support this function.

One example of a bus that does this is CacheBus. This bus supports caching portions of a (presumably slow) bus backed by registers.

If the forceall parameter is non-zero, all segments will be written, otherwise only those segments which are marked as dirty will be written.

Request

[@host] Bus[:instance] Commit ForceAll

Reply

Examples: Coming Soon!

BitToggle8

This function performs an 8-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the inversion of its current value.

The BitNumber parameter must be in the range of 0 to 7.

The value returned is the new value of the bit.

Request

[@host] Bus[:instance] BitToggle8 Address BitNumber

Reply

BitToggle8

Examples: Coming Soon!

BitToggle16

This function performs a 16-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the inversion of its current value.

The BitNumber parameter must be in the range of 0 to 15.

The value returned is the new value of the bit.

Request

[@host] Bus[:instance] BitToggle16 Address BitNumber

Reply

BitToggle16

Examples: Coming Soon!

BitToggle32

This function performs a 32-bit read/modify/write to the bus at the specified Address. The modify will assign the specified BitNumber of the value to the inversion of its current value.

The BitNumber parameter must be in the range of 0 to 31.

The value returned is the new value of the bit.

Request

[@host] Bus[:instance] BitToggle32 Address BitNumber

Reply

BitToggle32

Examples: Coming Soon!

Assign8X

This function performs an 8-bit read/modify/write to the bus at the specified Address in order to replace bits from BitMSB down to BitLSB, inclusively, with the specified Value.

The values of BitMSB and BitLSB must be in the range of 0 to 7, inclusively, and BitMSB must be greater than or equal to BitLSB.

Only the bottom-most (BitMSB - BitLSB) bits of value are assigned.

This function returns the new value written to the address.

Request

[@host] Bus[:instance] Assign8X Address BitMSB BitLSB Value

Reply

Assign8X

Examples: Coming Soon!

Assign16X

This function performs a 16-bit read/modify/write to the bus at the specified Address in order to replace bits from BitMSB down to BitLSB, inclusively, with the specified Value.

The values of BitMSB and BitLSB must be in the range of 0 to 15, inclusively, and BitMSB must be greater than or equal to BitLSB.

Only the bottom-most (BitMSB - BitLSB) bits of value are assigned.

This function returns the new value written to the address.

Request

[@host] Bus[:instance] Assign16X Address BitMSB BitLSB Value

Reply

Assign16X

Examples: Coming Soon!

Assign32X

This function performs a 32-bit read/modify/write to the bus at the specified Address in order to replace bits from BitMSB down to BitLSB, inclusively, with the specified Value.

The values of BitMSB and BitLSB must be in the range of 0 to 31, inclusively, and BitMSB must be greater than or equal to BitLSB.

Only the bottom-most (BitMSB - BitLSB) bits of value are assigned.

This function returns the new value written to the address.

Request

[@host] Bus[:instance] Assign32X Address BitMSB BitLSB Value

Reply

Assign32X

Examples: Coming Soon!

BitsGet8

This function performs an 8-bit read of the value at the specified Address, and returns the value of the bits from BitMSB down to BitLSB, inclusively. This effectively is the same as masking out all bits above BitMSB and shifting the result down (right) by BitLSB bits.

The values of BitMSB and BitLSB must be in the range of 0 to 7, inclusively, and BitMSB must be greater than or equal to BitLSB.

Request

[@host] Bus[:instance] BitsGet8 Address BitMSB BitLSB

Reply

BitsGet8

Examples: Coming Soon!

BitsGet16

This function performs a 16-bit read of the value at the specified Address, and returns the value of the bits from BitMSB down to BitLSB, inclusively. This effectively is the same as masking out all bits above BitMSB and shifting the result down (right) by BitLSB bits.

The values of BitMSB and BitLSB must be in the range of 0 to 15, inclusively, and BitMSB must be greater than or equal to BitLSB.

Request

[@host] Bus[:instance] BitsGet16 Address BitMSB BitLSB

Reply

BitsGet16

Examples: Coming Soon!

BitsGet32

This function performs a 32-bit read of the value at the specified Address, and returns the value of the bits from BitMSB down to BitLSB, inclusively. This effectively is the same as masking out all bits above BitMSB and shifting the result down (right) by BitLSB bits.

The values of BitMSB and BitLSB must be in the range of 0 to 31, inclusively, and BitMSB must be greater than or equal to BitLSB.

Request

[@host] Bus[:instance] BitsGet32 Address BitMSB BitLSB

Reply

BitsGet32

Examples: Coming Soon!

Time

Wait

Blocks until at least the specified number of microseconds has passed, then returns the number of microseconds actually waited.

Uses the local system facilities to sleep for periods at least at long as the clock tick, and busy waits amounts of time shorter than this.

Request

[@host] Time[:instance] Wait microseconds

Reply

Wait

Examples: Coming Soon!

Delay

This function delays until at least the specified number of microseconds has passed. For the TCP object, this means that although the call will delay execution on the server it will not block on the client, allowing additional calls to be queued to the server during the delay.

The C function itself will block until the delay is finished.

Request

[@host] Time[:instance] Delay microseconds

Reply

Examples: Coming Soon!

Tick

A given instance of the time object has an underlying timer or periodically incremented counter which keeps time. The value of this counter is called the "tick". This function returns the current 32-bit value of this counter.

Request

[@host] Time[:instance] Tick

Reply

Tick

Examples: Coming Soon!

usElapsed

The start parameter to this function is the return value of a previous call to the Tick function. This function returns the number of microseconds that have passed since the call to Tick which returned the given start value.

A given Time object will have a maximum amount of elapsed time which can be measured before it will roll over and start at zero again. In addition, a 32-bit microsecond value can only represent a maximum of approximately 4295 seconds. If the Time object can measure longer intervals than this the usElapsed64 function (currently not defined) should be called instead.

Request

[@host] Time[:instance] usElapsed start

Reply

usElapsed

Examples: Coming Soon!

usFuture

This function returns the tick value for a time at the specified number of microseconds from the given start tick.

Calling this function one in conjunction with multple calls to TimeoutQ will generally be more efficient than repeatedly calling usElapsed for determining when a specified amount of time has passed.

Request

[@host] Time[:instance] usFuture start microseconds

Reply

usFuture

Examples: Coming Soon!

TimeoutQ

This function returns true if the specified end time relative to the specified start time has been reached.

Note that since the tick value can roll over, the actual amount of time available to detect a timeout is equal to the total time for the tick to iterate through all values, minus the number of ticks between start and end. (end can be less than start; this function will correctly handle roll-over). Therefore, it is recommended that the user not try to measure times too close to the maximum possible (for example, within a few seconds, or the maximum amount of time between calls to TimeoutQ.)

If start and end are equal, then this function will always return true.

Request

[@host] Time[:instance] TimeoutQ start end

Reply

TimeoutQ

Examples: Coming Soon!

TPS

This function returns the number of ticks per second that the timebase used by this Time object ticks at.

Request

[@host] Time[:instance] TPS

Reply

TPS

Examples: Coming Soon!

Pin

Lock

This function acquires or releases the Pin resource lock. The should must be held before any other functions are called if there is any chance of other processes competing to access the same pins.

The num parameter is the Pin number to lock.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the Pin lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] Pin[:instance] Lock num flags

Reply

Lock

Examples: Coming Soon!

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.

Request

[@host] Pin[:instance] Unlock num flags

Reply

Unlock

Examples: Coming Soon!

Preempt

tsctlPinPreemptDesc Coming Soon!

Request

[@host] Pin[:instance] Preempt

Reply

Preempt

Examples: Coming Soon!

ModeGet

This function returns the current mode of the specified PinNumber.

Request

[@host] Pin[:instance] ModeGet PinNumber

Reply

ModeGet

ModeSet

This function sets the mode of the specified PinNumber to the specified Mode.

Available modes include MODE_DIO, MODE_CAN, MODE_SPI, MODE_ADC, MODE_TWI, MODE_UART, MODE_TS, MODE_BUS, MODE_PWM, and MODE_CLK, although most of these are usually not applicable.

Request

[@host] Pin[:instance] ModeSet PinNumber Mode

Reply

ModeSet

DIORaw

Lock

This function acquires or releases the DIORaw resource lock. The lock must be acquired before calling other DIORaw functions.

The num parameter is the DIORaw number to lock.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the DIORaw lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] DIORaw[:instance] Lock num flags

Reply

Lock

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.

Request

[@host] DIORaw[:instance] Unlock num flags

Reply

Unlock

Preempt

Request

[@host] DIORaw[:instance] Preempt

Reply

Preempt

DirSet

The specified raw DIO num, relative to the object, is set to an output if asOutput is true, otherwise it is set to an input.

Request

[@host] DIORaw[:instance] DirSet num asOutput

Reply

DataSet

The data output of the specified raw DIO num, relative to the object, is set to high if asHigh is true, otherwise it is set to low. If the DIO is not currently set as an output this will have no effect on the DIO until it is set to an output.

Request

[@host] DIORaw[:instance] DataSet num asHigh

Reply

DirGet

Returns the directional state of the specified raw DIO num, relative to the object. A true return indicates the DIO is an output, while a false return indicates it is an input.

Request

[@host] DIORaw[:instance] DirGet num

Reply

DirGet

DataGet

Returns the actual (not set) state of the specified raw DIO num, relative to the object. A true return indicates the DIO is high, while a false return indicates it is an low.

Request

[@host] DIORaw[:instance] DataGet num

Reply

DataGet

Count

Returns the number of DIOs in the object. All DIOs in the object are numbered sequential, starting at 0 and ending at one less than the count returned.

Request

[@host] DIORaw[:instance] Count

Reply

Count

DIO

Lock

This function acquires or releases the DIO resource lock. The lock must be acquired before calling other DIO functions if there is any chance of another process trying to simultaneously access the DIO. The DIO lock also automatically set the mode of the pin corresponding to the DIO to DIO mode. If the lock is not acquired, the ModeSet of the Pin class must be called appropriately to do this (if needed).

The num parameter is the DIO number to lock.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the DIO lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] DIO[:instance] Lock num flags

Reply

Lock

Examples: Coming Soon!

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.

Request

[@host] DIO[:instance] Unlock num flags

Reply

Unlock

Preempt

Request

[@host] DIO[:instance] Preempt

Reply

Preempt

Refresh

The Refresh command causes all synchronous DIO values to update from their current hardware value. Subsequent calls to Get will return the value of each DIO at the last Refresh.

Refresh must always be called at the start of a set of synchronous DIO operations, in order to synchronize the DIO cache with the actual state of the DIOs.

Request

[@host] DIO[:instance] Refresh

Reply

Examples: Coming Soon!

Commit

The Commit command causes all synchronous DIO values to be update to hardware. All calls to Set which have changed the cached value of a DIO since the last Commit will cause the hardware value for that DIO to be updated.

Regardless of how many DIOs change in a single register, the register will be written at most once for a given commit, and not at all if no DIO values have changed since the last Commit.

In general, a Commit should be issued at the end of a set of synchronous DIO operations, in order to synchronize the DIO cache with the actual state of the DIOs. The Commit command only detects synchronous changes, therefore mixing synchronous and asynchronous DIO access must be done with care. More specifically, any asynchronous changes that occur between a Refresh and a Commit will not be detected and may result in the Commit not causing a DIO to reflect the cached state, specifically if the asynchronous change causes a DIO to not match its cached state and the cache state is not marked as dirty.

Request

[@host] DIO[:instance] Commit ForceAll

Reply

Examples: Coming Soon!

Set

Set the synchronous DIO with logical number DIONum relative to the DIO instance to the specified State.

The Refresh function must be called before this function.

The actual DIO state wil not be updated until the next call to Commit.

typedef enum {
  INPUT_LOW=-3, // DIO is an INPUT and read LOW
  INPUT_HIGH=-2, // DIO is an INPUT and read HIGH
  INPUT=-1, // set DIO to an INPUT
  LOW=0, // set DIO to an OUTPUT and drive LOW
  HIGH=1 // set DIO to an OUTPUT and drive HIGH
} DIOState;

Request

[@host] DIO[:instance] Set DIONum State

Reply

Examples: Coming Soon!

Get

The function returns the synchronous state of the specified DIO DIONum relative to the DIO object. The value returned is the state of the DIO as of the last Refresh call.

typedef enum {
  INPUT_LOW=-3, // DIO is an INPUT and read LOW
  INPUT_HIGH=-2, // DIO is an INPUT and read HIGH
  INPUT=-1, // set DIO to an INPUT
  LOW=0, // set DIO to an OUTPUT and drive LOW
  HIGH=1 // set DIO to an OUTPUT and drive HIGH
} DIOState;

Request

[@host] DIO[:instance] Get DIONum

Reply

Get

SetAsync

Set the asynchronous (current) value of the DIO with logical number DIONum relative to the DIO instance to the specified State.

The value is not reflected in the synchronous side of the DIO. For example, if the synchronous value differs from the asynchronous value and a Commit is performed, the asynchronous change will not be detected and the value of the output may or may not be changed depending on whether other DIO values in the same register changes. Because of this indeterminate or difficult to predict behavior mixing of synchronous and asynchronous calls must be done with care.

typedef enum {
  INPUT_LOW=-3, // DIO is an INPUT and read LOW
  INPUT_HIGH=-2, // DIO is an INPUT and read HIGH
  INPUT=-1, // set DIO to an INPUT
  LOW=0, // set DIO to an OUTPUT and drive LOW
  HIGH=1 // set DIO to an OUTPUT and drive HIGH
} DIOState;

Request

[@host] DIO[:instance] SetAsync DIONum State

Reply

GetAsync

The function returns the asynchronous (current) state of the specified DIO DIONum relative to the DIO object.

typedef enum {
  INPUT_LOW=-3, // DIO is an INPUT and read LOW
  INPUT_HIGH=-2, // DIO is an INPUT and read HIGH
  INPUT=-1, // set DIO to an INPUT
  LOW=0, // set DIO to an OUTPUT and drive LOW
  HIGH=1 // set DIO to an OUTPUT and drive HIGH
} DIOState;

Request

[@host] DIO[:instance] GetAsync DIONum

Reply

GetAsync

Wait

The nh Array contains elements which are DIO numbers which match if they are high.

The nl Array contains elements which are DIO numbers which match if they are low.

Waits until the total number of DIOs that match their respective states is between min and max, inclusively.

Upon entry, the length of the match Array must be allocated or null. If it is null, it is ignored. Otherwise, upon return, the match Array length will be resized to the number of DIOs that match and will contain the DIO numbers that matched. If the match Array was not long enough to hold all the DIOs that matched, then the DIOs reported are truncated to the size of the Array as passed by the caller and it is returned length unchanged.

This function polls at the closest available interval to 10ms possible, using Time instance 1 (if available), or Time instance 0 (if instance 1 is not present).

Request

[@host] DIO[:instance] Wait match.Length min max nh nl

Reply

Count

Returns the number of DIOs in the object. All DIOs in the object are numbered sequential, starting at 0 and ending at one less than the count returned

Unlike other functions (besides Lock), the DIO object does not need to be locked when this function is called.

Request

[@host] DIO[:instance] Count

Reply

Count

Capabilities

This function returns the capabilities the DIO number num.

typedef enum DIOCaps{
  DIO_NOT_PRESENT=0,
  DIO_CAN_INPUT=1,
  DIO_CAN_DRIVE_HIGH=2,
  DIO_HIGH_SIDE=3,
  DIO_CAN_DRIVE_LOW=4,
  DIO_LOW_SIDE=5,
  DIO_OUTPUT_ONLY=6,
  DIO_NORMAL=7
}DIOCaps;

Request

[@host] DIO[:instance] Capabilities num

Reply

Capabilities

GetMulti

The function returns the current state of all or some of the DIOs in this instance.

Each byte in the state array is packed with 8 DIO values. The most significant bit of bits[0] contains the value of the logical DIO numbered offset. The next most significant bit contains the value of logical DIO offset+1 and so forth, moving to the next element of bits every time the current element has be filled with the next 8 DIO values.

Each bit upon return contains only the value of the DIO, either 1 for HIGH or 0 for LOW. No indication is returned whether the DIO is an INPUT or OUTPUT.

It is up to the user to correctly size the state Array. If the size is longer than the remaining number of DIO from the starting offset the value of the remaining bits will be undefined. To find the optimal Array length for bits, take the number of DIOs in the instance, as reported by the Count function, and subtract the starting offset. Then, divide by 8, adding one if there is a remainder.

A smaller than optimal size can be specified in order to reduce the range of DIO values returned. In this way it is possible to use this function to return any contiguous subset of DIO values.

This function also supports a "quick" mode. If 32 or fewer bits are needed, pass a zero-length state Array or null pointer for bits, and the return value will be the first 32 DIOs starting at offset with the most significant bit being the value of the logical DIO numbered offset.

Request

[@host] DIO[:instance] GetMulti state.Length offset

Reply

GetMulti

TWI

Lock

This function acquires or releases the TWI resource lock. The lock must be acquired before calling other TWI functions.

The num parameter is 0.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the TWI lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] TWI[:instance] Lock num flags

Reply

Lock

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.

Request

[@host] TWI[:instance] Unlock num flags

Reply

Unlock

Preempt

tsctlTWIPreemptDesc Coming Soon!

Request

[@host] TWI[:instance] Preempt

Reply

Preempt

Examples: Coming Soon!

Write

This function writes a frame to the two-wire interface.

The devadr parameter specifies the address of the device to talk to.

The adrslen parameter specifies the length of the register address in the device. Valid values for this parameter are 0 through 4.

The adrs parameter specifies the address in the device to write to. If adrslen is 0, this value is ignored. The bytes in the adrs are sent LSB first

The bytes is an Array containing the data to send.

Request

[@host] TWI[:instance] Write devadr adrslen adrs bytes

Reply

Write

Read

This function reads a frame from the two-wire interface.

The devadr parameter specifies the address of the devise to talk to.

The adrslen parameter specifies the length of the register address in the device. Valid values for this parameter are 0 through 4.

The adrs parameter specifies the address in the device to read from. If adrslen is 0, this value is ignored. The bytes in the adrs are sent LSB first.

The bytes parameter contains an Array to receive the data read, with the length of the Array being the number of bytes to read.

Request

[@host] TWI[:instance] Read devadr adrslen adrs bytes.Length

Reply

Read

CAN

Rx

Blocks until a message is received from CAN. The message is put into the CANmessage buffer passed by the caller.

In direct mode all available CPU will be used to poll for a message to be received. If this is a problem it is recommended to use the CAN server which uses interrupts.

Returns a positive return value if a message was received into the buffer provided, or a negative value if the receive was aborted. The latter could occur if Abort was explicitly called before the message was received, or if another error such as a Bus Off condition occurred.

struct CANMessage {
  unsigned flags;
  unsigned id;
  unsigned t_sec;
  unsigned t_usec;
  unsigned length;
  unsigned char data[8];
};


typedef enum CANFlags{
  FLAG_BUS_ERROR=1,
  FLAG_ERROR_PASSIVE=2,
  FLAG_DATA_OVERRUN=4,
  FLAG_ERROR_WARNING=8,
  FLAG_RTR=16,
  FLAG_EXT_ID=32,
  FLAG_LOCAL=64,
  FLAG_CONTROL=128
} CANFlags;


The timestamp fields (t_sec, t_usec) contain the server time when the CAN packet was received. For performance reasons some servers may not implement this and may fill these fields with 0.

The length field indicates how many bytes of data are in this CAN frame, and consequently, how many sequential bytes in the data field is valid.

Request

[@host] CAN[:instance] Rx

Reply

Rx

Tx

Queues A CAN message for transmission with the specified flags, id, and data.

This function will block until the message is queued. For direct access there typically is only room for a single message to be queued at once, and as a result if a message is already waiting to be sent, this function will use all available CPU to poll waiting for the transmit buffer to be empty. Therefore, this function is not recommended to be used in direct mode in cases where this would be a problem.

Returns a negative value on error or a positive value on success.

Request

[@host] CAN[:instance] Tx flags id data

Reply

Tx

BaudSet

Change the baud rate of the CAN medium to the closest supported value to that requested. Returns the actual baud rate on return.

The baud rate should always be set before attempting to send or receive any messages. The tsctl client in direct mode retains the previous baud rate between invocations so it is not necessary to set it with each invocation.

On error, a negative error code is returned.

Request

[@host] CAN[:instance] BaudSet opt_baud

Reply

BaudSet

BaudGet

Returns the current baud rate of the CAN medium.

Request

[@host] CAN[:instance] BaudGet

Reply

BaudGet

Abort

Queues an abort. The purpose of this function is to cancel a pending transmit or receive, which normally block until completion. Abort is signal safe, so it is ideal for using from an alarm or signal handler.

When Tx is called to transmit a message, it will block until the transmit buffering mechanism is ready to accept a message to send. If an abort is pending, the check will be cancelled, the abort cleared, and the Tx function will return a negative error code.

When Rx or RxMulti is called to receive a message (or messages), it will first check if a message is ready to be received, and if not, it will block until a message is ready. If an abort is pending, the check will be cancelled, the abort cleared, and the Rx or RxMulti function will return a negative error code.

Request

[@host] CAN[:instance] Abort

Reply

RxMulti

Blocks until at least min messages are received from CAN. The messages received are put into the CANMessage Array msg passed by the caller. Upon entry, the length of this Array must be equal to the maximum number of messages desired. Upon return, the length will be the actual number of messages received.

The return value will be the number of messages received, unless the receive was aborted, in which case a negative value will be returned. The latter could occur if Abort was explicitly called before the message was received, or if another error such as a Bus Off condition occurred.

Request

[@host] CAN[:instance] RxMulti msg.Length min

Reply

RxMulti

SPI

Lock

This function acquires or releases the SPI resource lock. The lock must be acquired before calling other SPI functions.

The num parameter is 0.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the SPI lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] SPI[:instance] Lock num flags

Reply

Lock

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.

Request

[@host] SPI[:instance] Unlock num flags

Reply

Unlock

Preempt

Request

[@host] SPI[:instance] Preempt

Reply

Preempt

Write

This function initiates a transaction on the SPI bus. The bytes in the Array buf for the length of the Array are written to the SPI bus during the transaction, and the bytes read in are discarded. The chip select line to be asserted is specified by adrs. If the value of adrs is negative, the chip select line will not be de-asserted at the end of the write and -adrs is used as address; if adrs is positive then the chip select will be de-asserted at the end of the write. An adrs of 1 corresponds to CS0, an adrs of 2 corresponds to CS1, etc.

A positive value is returned on success, and a negative value on failure.

Request

[@host] SPI[:instance] Write adrs buf

Reply

Write

Read

This function initiates a transaction on the SPI buf. The bytes in the Array buf for the length of the Array are filled in with bytes read from the SPI bus during the transaction. The bytes written to the bus during the transaction are undefined. The chip select line to be asserted is specified by adrs. If the value of adrs is negative, the chip select line will not be de-asserted at the end of the read and -adrs is used as address; if adrs is positive then the chip select will be de-asserted at the end of the read. An adrs of 1 corresponds to CS0, an adrs of 2 corresponds to CS1, etc.

A positive value is returned on success, and a negative value on failure.

Request

[@host] SPI[:instance] Read adrs buf.Length

Reply

Read

ReadWrite

This function initiates a transaction on the SPI bus. The bytes in the Array wbuf for the length of the Array are written to the SPI bus during the transaction, and the bytes in rbuf for the same length are filled in with bytes read from the SPI bus during the same transaction. The chip select line to be asserted is specified by adrs. If the value of adrs is negative, the chip select line will not be de-asserted at the end of the readwrite and -adrs is used as address; if adrs is positive then the chip select will be de-asserted at the end of the read/write. An adrs of 1 corresponds to CS0, an adrs of 2 corresponds to CS1, etc.

A positive value is returned on success, and a negative value on failure.

Request

[@host] SPI[:instance] ReadWrite adrs wbuf rbuf.Length

Reply

ReadWrite

ClockSet

This function changes the clock speed of the SPI bus to the given hz frequency. Depending on the hardware present, the actual frequency may be different from what is specified, however it will never be faster than the value specified.

A positive value is returned on success, and a negative value on failure.

Request

[@host] SPI[:instance] ClockSet hz

Reply

ClockSet

EdgeSet

This function changes the edge on which SPI data is clocked.

The posedge parameter encodes both the standard CPOL and CPHA parameters, which are defined as follows:

  • CPOL is the base (inactive) clock state
  • CPHA is the edge to sample on (0=1st or leading, 1=2nd or trailing). Data changes on the opposite edge than it is sampled on. MOSI and MISO change on the same clock edge.

When positive, the posedge parameter primarily denotes the value of CPOL. When negative, the logical bit-wise note of this parameter denotes the value of CPOL. (-1 means CPOL=0 and -2 means CPOL=1)

When posedge is non-negative, CPHA=0. When it is negative, CPHA=1.

The following table summarizes these relationships:

posedgeCPOLCPHA
110
000
-101
-211

Note:The TS-4500/TS-4700/TS-4800 have only CPHA=0, with the posedge parameter being equal to CPOL.

A positive value is returned on success, and a negative value on failure (i.e. if the device does not support the requested posedge value).

Request

[@host] SPI[:instance] EdgeSet posedge

Reply

EdgeSet

AIO

Lock

This function acquires or releases the AIO resource lock. The lock must be held before any other functions on the given AIO are called.

The num parameter is unused and should be set to 0.

The value of flags must be a bitwise OR of the following:

NONBLOCKING: If the AIO lock can be immediately acquired (without blocking) then it is and the call succeeds, otherwise the lock is not acquired and the call fails.

SHARED: If this flag is set, then a shared (read) lock will be attempted, otherwise an exclusive (write) lock will be attempted. An exclusive lock requires that no shared locks be held before it will succeed. A shared lock requires that no exclusive locks be help before it will succeed. Locking favors readers so as to prevent reader starvation.

NOUNLOCK: Normally, if the thread calling this function holds other locks and this function will block, the other locks held are temporarily dropped and are then re-acquired before the call returns, in order to prevent deadlock. Therefore, the call will not fail, but it could block indefinitely. However if this flag is present, then if other locks are held and the call would block, the function returns failure. Note: deadlock detection is currently disabled pending debugging efforts

This function returns a positive value on success, and a negative value on failure.

enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] AIO[:instance] Lock num flags

Reply

Lock

Examples: Coming Soon!

Unlock

This function releases lock num previously successfully acquired by a call to Lock. The flags parameter must be SHARED if the lock was acquired with that flag, otherwise it must be zero. The other flags do not apply to Unlock and should not be presented. It is an error to unlock with a different SHARED state than the lock was acquired with; the results in this case will be undefined.


enum {
NONBLOCKING=1, SHARED=2, NOUNLOCK=4
};

Request

[@host] AIO[:instance] Unlock num flags

Reply

Unlock

Preempt

Request

[@host] AIO[:instance] Preempt

Reply

Preempt

Type

typedef enum {
AIO_ADC=0, ADIO_DAC=1
} AIOType;

Returns AIO_ADC if the AIO instance corresponds to an Analog to Digital device, or AIO_DAC if the AIO instance corresponds to a Digital to Analog device.

Request

[@host] AIO[:instance] Type

Reply

Type

VoltageRangeList

This function returns an Array of allowed voltage ranges for each channel. The returned Array is dynamically allocated by the function but the caller is responsible for freeing it. The length of the Array is equal to the number of voltage ranges supported.

struct VoltageSubRange {
  float start, step;
  unsigned count;
};
struct VoltageRange {
  VoltageSubRange low,high;
};



Request

[@host] AIO[:instance] VoltageRangeList

Reply

VoltageRangeList

PrecisionList

This function returns a bit-field defining what precisions are possible. The nth bit set in the return indicates that n bits of precision are possible.

Request

[@host] AIO[:instance] PrecisionList

Reply

PrecisionList

PeriodRangeList

This function returns an Array of allowed sampling periods for each channel. The returned Array is dynamically allocated by the function but the caller is responsible for freeing it. The length of the Array is equal to the number of period ranges supported.

The period is always expressed in nano-seconds. A period of 0 indicates that the channel can be disabled.

The AIO_HZ() macro can be used to convert back and forth between Hz and nanoseconds.

struct PeriodRange {
  unsigned start, step, count;
};

Request

[@host] AIO[:instance] PeriodRangeList

Reply

PeriodRangeList

TriggerList

This function returns an Array of trigger numbers available. The returned Array is dynamically allocated by the function but the caller is responsible for freeing it. The length of the Array is equal to the number of triggers supported. Trigger 0 is universal and is not contained in the returned Array.

The meaning of a trigger signal number is implementation specific: consult the documentation for your hardware (below) for the meaning of various trigger numbers.

Negative values indicate triggering on a negative edge, while positive values indicate triggering on a positive edge. Zero indicates that conversion begins on demand, in response to a call to Get, Gets8/16/32, Put, Puts8/16/32, Ready, or Readys8/16/32. Note that conversion is always implicitly on-demand, as one of these aforementioned calls is required to begin any conversion.

Hardware Specific Triggers

WBMCP3428 - this is an I2C (TWI) A/D unit present on the TS-8390 and TS-81x0, accessed via the FPGA through a WishBone (WB) interface. Supported by TS-SOCKET boards TS-4200, TS-4500, and TS-4700.

  • No non-zero triggers are available.

ts8820

  • no non-zero triggers are available.

Request

[@host] AIO[:instance] TriggerList

Reply

TriggerList

Channels

The function returns the number of channels in this module. The channel numbers are zero indexed.

Request

[@host] AIO[:instance] Channels

Reply

Channels

Reset

This function resets the AIO to a default value. This will disable all channels that can be disabled, and will reset to default values the sample period, precision, trigger, and voltage range of each channel along with the interrupt trigger.

The default values for each AIO implementation are listed below.

ts8820ADC

  • all channels disabled
  • sample period: 10,000 ns for all channels enabled via ChannelEnable
  • precision: 16 bits
  • trigger: none
  • voltage range: -10V to +10V

ts8820DIO

  • not yet implemented

Request

[@host] AIO[:instance] Reset

Reply

ChannelEnable

This function enables (flag == true) or disables (flag == false) sampling for the specified channel ch.

If ChannelSamplePeriod has not been called for this channel since the last call to Reset, the default sample period will be used.

If ChannelPrecision has not been called for this channel since the last call to Reset, the default precision will be used.

If ChannelVoltageRange has not been called for this channel since the last call to Reset, the default voltage range will be used

If ChannelTrigger has not been called for this channel since the last call to Reset, the default trigger will be used.

Upon failure, a negative error code is returned to indicate that the request would result in an unsupported configuration. On success a positive value is returned.

Note that when configuring multiple channels, each interim configuration must be valid. If you have a lot of channels to configure you may wish to use the Configure function instead to configure all channels simultaneously.

Request

[@host] AIO[:instance] ChannelEnable ch flag

Reply

ChannelEnable

ChannelSamplePeriod

This function sets and returns the sample period for the specified channel ch to be the given number of nanoseconds ns. If the channel is not currently enabled, then the sample period will not take effect until ChannelEnable is called for this channel. Otherwise the change will take place immediately.

If a value of 0 is passed for ns, the current value in effect is returned unchanged.

Upon failure, a value of 0 is returned to indicate that the requested sample period cannot be set. If the sample period will not take effect immediately then this cannot occur, so the current sample period will be returned, since the one passed has not yet taken effect.

Request

[@host] AIO[:instance] ChannelSamplePeriod ch ns

Reply

ChannelSamplePeriod

ChannelPrecision

This function sets and returns the precision for the specified channel ch to be the given number of bit prec. If the channel is not currently enabled, then the precision will not take effect until ChannelEnable is called for this channel. Otherwise the change will take place immediately.

If a value of 0 is passed for prec, the current value in effect is returned unchanged.

Upon failure, a value of 0 is returned to indicate that the requested precision cannot be set. If the precision will not take effect immediately then this cannot occur, so the current precision will be returned, since the one passed has not yet taken effect.

Request

[@host] AIO[:instance] ChannelPrecision ch prec

Reply

ChannelPrecision

ChannelVoltageRange

This function sets the voltage range for the specified channel ch to be between low and high. If the channel is not currently enabled, then the voltage range will not take effect until ChannelEnable is called for this channel. Otherwise the change will take place immediately.

Upon failure, a negative value is returned to indicate that the requested voltage range cannot be set. If the range will not take effect immediately then this cannot occur, so the current range will be returned, since the one passed has not yet taken effect.

Request

[@host] AIO[:instance] ChannelVoltageRange ch low high

Reply

ChannelVoltageRange

Configuration

low, high, prec, rate, and trigger are Arrays having lengths equal to the number of channels.

Each element of each array is filled with the current configuration for the corresponding channel except for itrig,which is a single value for the entire module.

A positive value is returned indicating success.

low and high, upon return contain the actual voltage range in effect for each channel.

prec, upon return contains the actual (minimum) precision in bits for each channel

t, upon return contains the actual (maximum) period in ns for each channel. The AIO_HZ() macro can be used to convert back and forth between Hz and nanoseconds.

trigger, upon return contains the trigger signal for activating each channel

itrig, upon return contains the interrupt trigger signal. If this value is non-zero, then when the trigger occurs during a call to Gets8/16/32 or Puts8/16/32, the call will return immediately at the end of the current set of samples, even if the requested number of samples has not yet been taken. A value of zero disables the interrupt trigger.

Request

[@host] AIO[:instance] Configuration low.Length high.Length prec.Length t.Length trigger.Length

Reply

Configuration

ConfigureTest

Returns true (non-zero) if the specific configuration is legal, and false (0) if it is not.

low and high contain the desired voltage range in effect for each channel. The length of these Arrays must be equal to the number of channels.

prec contains the desired (minimum) precision in bits for each channel. The length of this Array must be equal to the number of channels.

t contains the desired (maximum) period in ns for each channel. The length of this Arrays must be equal to the number of channels. The AIO_HZ() macro can be used to convert back and forth between Hz and nanoseconds.

trigger contains the desired trigger signal for activating each channel. The length of this Arrays must be equal to the number of channels

itrig is the interrupt trigger signal. If this value is non-zero, then when the trigger occurs during a call to Gets or Puts, the call will return immediately at the end of the current set of samples, even if the requested number of samples has not yet been taken. A value of zero disables the interrupt trigger.

Request

[@host] AIO[:instance] ConfigureTest low high prec rate trigger itrig

Reply

ConfigureTest

Configure

If the specific configuration is legal, the AIOs are configured to that configuration and a positive value is returned. Otherwise a negative error code is returned. The length of all passed Arrays must be equal to the number of channels.

low and high contain the desired voltage range in effect for each channel.

prec contains the desired (minimum) precision in bits for each channel

t contains the desired (maximum) period in ns for each channel. The AIO_HZ() macro can be used to convert back and forth between Hz and nanoseconds.

trigger contains the desired trigger signal for activating each channel

itrig is the interrupt trigger signal. If this value is non-zero, then when the trigger occurs during a call to Gets8/16/32 or Puts8/16/32, the call will return immediately at the end of the current set of samples, even if the requested number of samples has not yet been taken. A value of zero disables the interrupt trigger.

Hardware capabilities differ; to ensure maximum conversion rates across platforms when using Get or Put, call Configure before each call to only enable the next channel to converted. This will also allow for different channel configurations that would not be legal when enabling multiple channels. For example, suppose an AIO supports either 100Hz sampling at 12 bits or 50Hz sampling at 16 bits. It would not be legal to enable channel 1 for 100Hz@12 bits and channel 2 for 50Hz@16 bits at the same time. However by only enabling one channel at a time in turn before sampling it would be possible to accomplish this as both configurations are not active simultaneously.

Calling Configure while a channel is active will cause the current activity to be terminated, either immediately or after the current sample is complete, depending on the capabilities of the hardware. Any data already waiting for a call to Get or Gets8/16/32 will be discarded.

Request

[@host] AIO[:instance] Configure low high prec rate trigger itrig

Reply

Configure

ITrig

Change the interrupt trigger for the AIO to the specified trigger. If an existing interrupt trigger has been set it will first be disabled, and any subsequent call to Gets or Puts that would have returned due to the trigger occurring before this call will no longer do so as if the previous trigger never occurred.

Returns a positive value on success, or a negative error code on failure.

Request

[@host] AIO[:instance] ITrig itrig

Reply

ITrig

Get

Only valid if AIO is an ADC. If the AIO is a DAC, simply returns the current value being output, e.g. via the last Puts call.

If the specified channel is currently active, waits for it to become inactive, then returns the value just sampled for that channel.

If a different channel is active, either waits for it to become inactive or immediately de-activates it (depending on what the hardware is capable of), then makes the specified channel active, waits for it to become inactive, then returns the value just sampled for that channel.

If the specified channel was the last channel active but has now finished, returns the value sampled for that channel.

If no channel is currently active, makes the specified channel active, waits for it to become inactive, then returns the value just sampled for that channel.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

Hardware capabilities differ; to ensure maximum conversion rates across platforms, call Configure() before each Get() or Ready() call to only enable the next channel to converted.

The value returned can be converted to the voltage on the input by the following relationship between the precision (p) in bits and input voltage range (IV) of the channel (max input voltage - minimum input voltage) and the actual voltage (V) as follows:

V = IV / 2^p

Request

[@host] AIO[:instance] Get channel

Reply

Get

Put

Only valid if AIO is a DAC. Return value is a negative error code if AIO is not a DAC and a positive value if the specified value has begun DAC conversion.

If any channel is currently active, waits for it to become inactive, then makes the specified channel active with the specified value to convert, and returns a positive value.

If no channel is currently active, then makes the specified channel active with the specified value to convert, and returns a positive value.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

Hardware capabilities differ; to ensure maximum conversion rates across platforms, call Configure before each Get or Ready call to only enable the next channel to converted.

The value passed relates to the voltage to be generated on the output by the following relationship between the precision (p) in bits and output voltage range (OV) of the channel (maximum output voltage - minimum output voltage) and the actual voltage (V) as follows:

V = OV / 2^p

Request

[@host] AIO[:instance] Put channel value

Reply

Put

Ready

Returns a negative error code if the AIO unit does not support polled conversion. In that case you must call one of the blocking functions instead, i.e. Get, Put, Gets, or Puts as appropriate.

If the specified channel is currently active, returns 0.

If a different channel is active, or an invalid channel was passed, returns a negative error code.

If the specified channel was the last channel active but has now finished, returns a positive value.

If no channel is currently active, makes the specified channel active and returns 0.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

A non-positive return value indicates that a subsequent call to Get (for ADC) or Put (for DAC) will block, unless the error code indicates an invalid channel was passed, in which case nothing can be deduced about whether the Get or Put call will block.

Calling Gets (for ADC), Puts (for DAC), or Readys (for either) will override the behavior of this call.

Request

[@host] AIO[:instance] Ready channel

Reply

Ready

Gets8

This call is only valid if AIO is an ADC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been taken for each channel and placed into the specified buffer, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The function may also return less than the requested number of samples of an overflow or other such error occurs. If fewer than the requested number of samples are returned, the next call may return a negative error code, and the following call will restart acquisition. The intervening error code allows the caller to determine what went wrong, and to resynchronize acquisition. For example, if an overflow occurs, the remaining data before the overflow will be returned, after which the caller will learn of the overflow and can take whatever steps are necessary due to missing samples at that point.

This function is only suitable for calling if the precision of all channels to be sampled is less than or equal to eight bits. Channels that have a higher precision will return truncated data. The format of the data put in the passed array is such that each sampled channel is added in turn. After the last channel is sampled the next sample will start over the with first channel. The length of the Array determines how many samples will be taken: it is not necessary to take a sample of every channel, and if the length of the Array is not an even multiple of the number of channels being sampled the last sampling will not contain all channels.

Request

[@host] AIO[:instance] Gets8 buf.Length

Reply

Gets8

Gets16

This call is only valid if AIO is an ADC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been taken for each channel and placed into the specified buffer, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The function may also return less than the requested number of samples of an overflow or other such error occurs. If fewer than the requested number of samples are returned, the next call may return a negative error code, and the following call will restart acquisition. The intervening error code allows the caller to determine what went wrong, and to resynchronize acquisition. For example, if an overflow occurs, the remaining data before the overflow will be returned, after which the caller will learn of the overflow and can take whatever steps are necessary due to missing samples at that point.

This function is only suitable for calling if the precision of all channels to be sampled is less than or equal to sixteen bits. Channels that have a higher precision will return truncated data. The format of the data put in the passed array is such that each sampled channel is added in turn. After the last channel is sampled the next sample will start over the with first channel. The length of the Array determines how many samples will be taken: it is not necessary to take a sample of every channel, and if the length of the Array is not an even multiple of the number of channels being sampled the last sampling will not contain all channels.

Request

[@host] AIO[:instance] Gets16 buf.Length

Reply

Gets16

Gets32

This call is only valid if AIO is an ADC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been taken for each channel and placed into the specified buffer, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The function may also return less than the requested number of samples of an overflow or other such error occurs. If fewer than the requested number of samples are returned, the next call may return a negative error code, and the following call will restart acquisition. The intervening error code allows the caller to determine what went wrong, and to resynchronize acquisition. For example, if an overflow occurs, the remaining data before the overflow will be returned, after which the caller will learn of the overflow and can take whatever steps are necessary due to missing samples at that point.

This function is only suitable for calling if the precision of all channels to be sampled is less than or equal to 32 bits. Channels that have a higher precision will return truncated data. The format of the data put in the passed array is such that each sampled channel is added in turn. After the last channel is sampled the next sample will start over the with first channel. The length of the Array determines how many samples will be taken: it is not necessary to take a sample of every channel, and if the length of the Array is not an even multiple of the number of channels being sampled the last sampling will not contain all channels.

Request

[@host] AIO[:instance] Gets32 buf.Length

Reply

Gets32

Puts8

This call is only valid if AIO is a DAC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been converted from the buffer for each channel, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The number of elements in the passed Array determines how many samples will be written. Each sample will be written to a subsequent channel, wrapping around at the end. It is not required that the length be an exact multiple of the number of channels.

Request

[@host] AIO[:instance] Puts8 buf

Reply

Puts8

Puts16

This call is only valid if AIO is a DAC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been converted from the buffer for each channel, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The number of elements in the passed Array determines how many samples will be written. Each sample will be written to a subsequent channel, wrapping around at the end. It is not required that the length be an exact multiple of the number of channels.

Request

[@host] AIO[:instance] Puts16 buf

Reply

Puts16

Puts32

This call is only valid if AIO is a DAC. Otherwise a negative error value will be returned.

If the specified buffer was successfully passed to Readys, then this call will block until that conversion is completed. Otherwise, the conversion will be initiated immediately such that each enabled channel will be activated in turn, looping around until the specified number of samples have been converted from the buffer for each channel, with the function blocking until all conversions are completed or the interrupt trigger occurs. In either case, a positive return code will be returned indicating the number of samples actually taken.

The number of elements in the passed Array determines how many samples will be written. Each sample will be written to a subsequent channel, wrapping around at the end. It is not required that the length be an exact multiple of the number of channels.

Request

[@host] AIO[:instance] Puts32 buf

Reply

Puts32

Readys8

This function prepares a buffer for high speed conversion if supported by the hardware. For an ADC, this sets up the specified buffer to automatically receive the specified number of samples in the Array on the enabled channels, while for a DAC it sets up the specified buffer as containing the values to automatically convert to analog outputs. After the buffer has been set up the hardware is set up to activate the first enabled channel and then automatically activate each subsequent channel in turn as soon as the previous one de-activates, looping back around to the first enabled channel after the last enabled channel has de-activated as long as more samples remain.

For some hardware it may be necessary to match which Readys function is called to the size of the samples expected by the hardware. For example, a 16-bit A/D that supports DMA may require that Readys16 be called because it transfers 16-bit values. Or, it might require 32-bit values even though it takes 16-bit samples. Check for any notes for your hardware to determine if this is the case.

Returns a positive value on success. This indicates that the given buffer has been accepted for queuing.

A negative return value indicates failure. Possible failures include:

  • the specified buffer is already (still) in use. (note: you must deliberately try to provoke this error to determine if a previously requested conversion is completed)
  • the hardware has a limited amount of space for queuing and cannot accept an additional buffer at this time
  • the buffer passed does not conform to hardware requirements, such as alignment
  • the hardware does not support buffer queueing. it is still possible to call Gets or Puts as appropriate but those functions will block until the requested buffer is filled or used up.

Any previous conversion in progress caused by Ready will be finished or cancelled (depending on hardware capabilities) before this request is serviced.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

Request

[@host] AIO[:instance] Readys8 buf

Reply

Readys8

Readys16

This function prepares a buffer for high speed conversion if supported by the hardware. For an ADC, this sets up the specified buffer to automatically receive the specified number of samples in the Array on the enabled channels, while for a DAC it sets up the specified buffer as containing the values to automatically convert to analog outputs. After the buffer has been set up the hardware is set up to activate the first enabled channel and then automatically activate each subsequent channel in turn as soon as the previous one de-activates, looping back around to the first enabled channel after the last enabled channel has de-activated as long as more samples remain.

For some hardware it may be necessary to match which Readys function is called to the size of the samples expected by the hardware. For example, a 16-bit A/D that supports DMA may require that Readys16 be called because it transfers 16-bit values. Or, it might require 32-bit values even though it takes 16-bit samples. Check for any notes for your hardware to determine if this is the case.

Returns a positive value on success. This indicates that the given buffer has been accepted for queuing.

A negative return value indicates failure. Possible failures include:

  • the specified buffer is already (still) in use. (note: you must deliberately try to provoke this error to determine if a previously requested conversion is completed)
  • the hardware has a limited amount of space for queuing and cannot accept an additional buffer at this time
  • the buffer passed does not conform to hardware requirements, such as alignment
  • the hardware does not support buffer queueing. it is still possible to call Gets or Puts as appropriate but those functions will block until the requested buffer is filled or used up.

Any previous conversion in progress caused by Ready will be finished or cancelled (depending on hardware capabilities) before this request is serviced.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

Request

[@host] AIO[:instance] Readys16 buf

Reply

Readys16

Readys32

This function prepares a buffer for high speed conversion if supported by the hardware. For an ADC, this sets up the specified buffer to automatically receive the specified number of samples in the Array on the enabled channels, while for a DAC it sets up the specified buffer as containing the values to automatically convert to analog outputs. After the buffer has been set up the hardware is set up to activate the first enabled channel and then automatically activate each subsequent channel in turn as soon as the previous one de-activates, looping back around to the first enabled channel after the last enabled channel has de-activated as long as more samples remain.

For some hardware it may be necessary to match which Readys function is called to the size of the samples expected by the hardware. For example, a 16-bit A/D that supports DMA may require that Readys16 be called because it transfers 16-bit values. Or, it might require 32-bit values even though it takes 16-bit samples. Check for any notes for your hardware to determine if this is the case.

Returns a positive value on success. This indicates that the given buffer has been accepted for queuing.

A negative return value indicates failure. Possible failures include:

  • the specified buffer is already (still) in use. (note: you must deliberately try to provoke this error to determine if a previously requested conversion is completed)
  • the hardware has a limited amount of space for queuing and cannot accept an additional buffer at this time
  • the buffer passed does not conform to hardware requirements, such as alignment
  • the hardware does not support buffer queueing. it is still possible to call Gets or Puts as appropriate but those functions will block until the requested buffer is filled or used up.

Any previous conversion in progress caused by Ready will be finished or cancelled (depending on hardware capabilities) before this request is serviced.

A channel goes through the following states:

  1. When a channel is first made active, it waits for its trigger to occur. If its trigger is "on demand" then not wait is done at this step.
  2. The channel remains active while conversion begins and proceed.
  3. When conversion is finished, the channel becomes inactive as well as the last channel active.

Request

[@host] AIO[:instance] Readys32 buf

Reply

Readys32

EDIO

Lock

Request

[@host] EDIO[:instance] Lock num flags

Reply

Lock

Unlock

Request

[@host] EDIO[:instance] Unlock num flags

Reply

Unlock

Preempt

Request

[@host] EDIO[:instance] Preempt

Reply

Preempt

QueryFunction

Return a list of top-level logical DIO numbers which support the specified EDIO function type. The type parameter must be one of the following:

typedef enum EDIOType {
  EDIO_PWM=1,
  EDIO_QUADRATURE=2,
  EDIO_EDGECOUNT=3,
  EDIO_GLITCHED=4
} EDIOType;

Request

[@host] EDIO[:instance] QueryFunction type

Reply

QueryFunction

PWM

Set the given DIO to begin producing PWM of the specified parameters on the given DIO num. The periodHigh and periodLow are specified in nanoseconds. If the specific DIO does not support the specified high/low period, priority will be given to setting a duty cycle as close to that implied by periodHigh / (periodHigh + periodLow), using the closest supported frequency.

Request

[@host] EDIO[:instance] PWM num periodHigh periodLow

Reply

PWM

QueryPWM

Returns the PWM high and low period for the specified DIO.

Returns a positive value on success, or a negative error code if the specified DIO number cannot do PWM.

Request

[@host] EDIO[:instance] QueryPWM num

Reply

QueryPWM

PWMfd

Set the given DIO to begin producing PWM of the specified parameters on the given DIO num. The mfreq parameter gives the frequency in milliHertz and the uDC parameter gives the duty cycle in millionths of a percent.

If the specific DIO does not support the specified frequency and duty cycle, the closest available frequency and duty cycle will be used.

Request

[@host] EDIO[:instance] PWMfd num freq DC

Reply

PWMfd

QueryPWMfd

Returns the PWM frequency in milliHertz and duty cycle in millionths of a percent.

Returns a positive value on success, or a negative error code if the specified DIO number cannot do PWM.

Request

[@host] EDIO[:instance] QueryPWMfd num

Reply

QueryPWMfd

QuadratureCount

Returns the quadrature count on the specific DIO.

Since quadrature actually requires two DIOs, there is always a secondary implied DIO on which the other part of the quadrature takes place. The user is responsible for looking up which DIO this is in the manual, as this API does not provide it.

The counter may be reset after this call.

Request

[@host] EDIO[:instance] QuadratureCount num

Reply

QuadratureCount

EdgeCount

This function returns the current value of the specified edge counter for pin number num. If edge is positive, then the value of the positive edge counter is returned. Ifedge is negative, then the value of the negative edge counter is returned. If edge is zero, then the value returned will be the sum of the positive and negative edge counters.

The edge counters always start at zero on power-up and increment until they reach the maximum possible value, at which point on the next edge they roll back over to zero. The maximum possible value for each counter is hardware dependant.

The return value is a 64-bit unsigned integer. This is sufficient to count at 1Ghz for over 584 years before roll-over occurs. However, not all hardware will support this size counter natively. Adapter objects in libtsctl will internally poll the edge counters in order to keep a 64-bit total counter, however these will have the limitation of missing edges if the input signal is changing too fast. How fast is too fast will depend on hardware counter side and to some extent CPU loading.

A value of zero will always be returned if the specified edge counter is not supported by the hardware for the given pin.

Request

[@host] EDIO[:instance] EdgeCount num edge

Reply

EdgeCount

Glitched

Returns true if the given DIO glitched since the last call to this function.

Request

[@host] EDIO[:instance] Glitched num

Reply

Glitched

HBridge

Sets the H-Bridge functionality of the specified pin num to the given state. The possible states are:

  • HB_LEFT : positive voltage is applied on the specified pin, with negative (or ground) on the auxiliary pin associated with this pin.
  • HB_RIGHT : positive voltage is applied on the auxiliary pin associated with the specified pin, with negative (or ground) on the specified pin itself.
  • HB_FREE_RUNNING : no voltage is applied across either pin
  • HB_BRAKING : both pins are connected to the same rail

Returns a negative error code if the specified pin cannot be used as an H-Bridge, or if the specified state is unsupported on this pin.

typedef enum HBState {
  HB_LEFT=1,HB_RIGHT=2,HB_FREE_RUNNING=3,HB_BRAKING=4
} HBState;

Request

[@host] EDIO[:instance] HBridge num state

Reply

HBridge