LabMap Handbook

The current local time in the format hh:mm.

Bounds error String Output LabMap.dll When bounds violation of a register leads to value loss, that is when the bounds violation reaction is either BoundsRRRDiscard or BoundsRRRSignal, then this string register receives the value: <no>#<value>. Here <no> is the register number, <value> is the discarded value in a printable format.

Bounds in Integer Output LabMap.dll This register contains the number of another register which value was most recently appeared with value bounds. Note that initially when bounds are first set the register is counted to be out of the bounds no matter of its actual value. Also when the register has several bounds then entering any number of them simultaneously would yield only one setting of the described register.

Bounds out Integer Output LabMap.dll This register contains the number of another register which value was most recently leaved value bounds. Initially when bounds are first set the register is counted to be out of the bounds no matter of its actual value. When the register has several bounds then leaving any number of them simultaneously would yield only one setting of the described register.

Bounds over Integer Output LabMap.dll This register contains the number of another register which value was most recently crossed an upper value bound. To catch both upper and lower bound violation, use the bounds out register instead. Initially when bounds are first set the register is counted to be out of the bounds no matter of its actual value. When the register has several bounds then leaving any number of them simultaneously would yield only one setting of the described register.

Bounds under Integer Output LabMap.dll This register is similar to the bounds over, but catches lower value bound violations.

Density Real
[g/cm³] Output LabPLU.dll The measured density (the hardware unit shall be set to g/cm³)

Handle to trace Integer Input LabMap.dll The number of the traced register.

Handle enqueued Integer Output LabMap.dll The last bit of this register's value is toggled each time an operation over the traced register is requested and, hence, a corresponding message is queued into the messages queue.

Handle I/O started Integer Output LabMap.dll The last bit of this register's value is toggled each time an I/O start message associated with the register is removed from the messages queue.

Handle I/O ended Integer Output LabMap.dll The last bit of this register's value is toggled each time a I/O operation associated with the register ends.

Host

String

Input

LabNet.dll

The name or IP address of the remote host. This register is initialized upon start with the value of Server.<Host> key from the registry. Sending this register causes reconnection to the host. This is the legal way to switch the interface from one remote server to another. The name or IP address may be followed by specification of the operating modes put in round brackets. The following modes are supported (case insensitive):

rw indicates the read-write mode (this is the default)
ro indicates the read-only mode.
sync[=<period>[:<factor>]] indicates the internal time synchronization. The parameter <period> indicates how frequently time synchronization packets should be sent (in ms, based). The default is 2000 (each two seconds). The field <factor> is a dissipation factor between 0.1 and 1.0. It determines how quickly old synchronization data are discarded. Each time a new data arrive the contribution of the old ones is multiplied to the factor. The default value is 0.99.
port=<port> specifies the TCP/IP port number (based) used for the connection. It has the same effect as the registry key Port.<Host>. The default is the value of the registry key. If no registry key exists, 1056 is used.
nodelay indicates that TCP_NODELAY option should be applied to the socket. This has the effect that outgoing requests will be sent immediately without an attempt to buffer it and thus to get a better data throughout. Note that this mode can have a significant negative impact on network and application performance, especially if a big amount of data is sent.
v=<version-number> specifies the version number of the LabNet protocol used for the connection. For LabMap^® versions lower than 4.0 it should be 1. The default for this parameter is the current version of the protocol.

The modes can be separated using spaces and/or commas. For instance: RRR.Hall_1.cars.com (ro). Here the registers are accessed in read-only mode using no internal time synchronization.

Host clock adjustment Real
[s] Output LabNet.dll The clock adjustment register. In the case of internal time synchronization with the remote host, this register is set each time clock adjustment is evaluated. The frequency is determined by the parameter sync of the connection. The value is the duration to add to a remote time stamp to get an equivalent local time stamp. The register shall have a time dimension. The register policy is ignored.

Host register number Integer Output LabNet.dll The remote register number. This register is used for browsing the remote registers. When the register is requested its actual value + 1 is used as the starting point of the search. After completion the value is either 0 or the number of a used remote register.

Host register name String Output LabNet.dll The remote register name. The name of the found remote register is stored here after a successful search using the host number register.

Host register status

Integer

Output

LabNet.dll

The remote register name. The status of the found remote register is stored here after a successful search using the host number register. The status contains the following bits properly set::

Type (HandleInteger, HandleReal, HandleString, HandleRecord)
State (HandleReady, HandleError, HandlePending, HandleUndefined)

Host register unit String Output LabNet.dll The remote register input units. The units of the found remote register is stored here after a successful search using the host number register. Note that this register is set only if a floating-point remote register was found.

Host round-trip time Real [s] Output LabNet.dll The round-trip time encountered during clock adjustment. In the case of internal time synchronization with the remote host, this register is set each time clock adjustment is evaluated. The frequency is determined by the parameter sync of the connection. The value is the round-trip time of the last time synchronization packet. The register shall have a time dimension. The register policy is ignored.

Last console log message

String

Output

The register contains the last message written to the console. The message format is:

<no> <server> <text>

Here <no> is the register number, <server> is the name of the interface reporting, <text> is the message text. The time stamp of the register is one of the message.

Log file String Input LabMap.dll The name of the log file. A send operation causes closing of the currently used log and opening a new one. The value can be empty. In this case the log file is closed without opening a new one.

Log handle on Integer Input LabMap.dll The number of a register to be marked for logging. A send operation causes the register with the number equal to the sent value to be marked for logging. When zero is provided all registers are marked.

Log handle off Integer Input LabMap.dll The number of a register to be unmarked for logging. A send operation causes the register with the number equal to the sent value to be unmarked for logging. When zero is provided all registers are unmarked.

Log status

Integer

Input

The status of the log file. When zero, it indicates that the log is inactive. Errors indicated by the register are associated with the log file operations. This register can be also used to control the log status:

Sent	Action	Description
-1	Graceful stop	If log is active, the system waits for new values of all registers marked for logging and only then stops the logging. The user application may wait for the handle value change to find out the moment when the logging is finally stopped. It is possible to do an unconditional logging stop when graceful stop is pending, by sending 0 into the register.
0	Unconditional stop	If log is active, the logging is stopped immediately. When post-processing the logged data, one should take into account that some registers might have no values defined at the right margin of the logging interval.
1	Start	If log is inactive it is started. All the registers marked for logging are logged if they have valid values and these values have not been logged.
2..100	Start with history snap-shot	If log is inactive it is started. All the registers marked for logging are logged including their present valid values and those available in the blackboard. The value sent determines how much of the blackboard contents should be scanned for the values, in percents counting from the time moment now back to the past. The values which have been logged before will not be logged twice. Blackboard scan percentages close to 100 are not recommended, because they suffer race condition and thus may cause a log fault, when the values requested are erased from the blackboard.

Missed scheduling time count Integer Output any
with device units The value, when requested returns the number of times when the registers of the specified units missed the next scheduling time. Note that when this register is queried manually rather than periodically, it would respond even if the unit is busy. The value is queried asynchronously to the unit thread.

name.x Real Input LabVirt.dll X-coordinate of the name-spline points (see also). When sent the value defines the x-coordinate of a spline point. Spline names are case insensitive.

name.y Real Input LabVirt.dll Y-coordinate of the name-spline points (see also). When sent a new point is added to the spline with the coordinates x, y, where x is the actual value of name.x and y is the value of name.y. Spline names are case insensitive.

name.reset Integer Input LabVirt.dll Reset register for the name-spline points (see also). When sent all the points of the spline name are removed. Spline names are case insensitive.

Owner String Output LabMap.dll The name of the user which currently has the access to the exclusively accessed registers

Parameters

String

Input

any
with device units

For the interfaces supporting multiple device units the register with this name is used to create, modify, delete units. The register value determines the unit parameters when sent:. The value of unit name register determines the unit name. Using LabMapSetString to set it appropriately before sending the parameters register.

Action

Description

Altering

When a non-empty string is sent, the value is the parameters to be set or changed. The syntax and meaning of the parameters depends on the concrete interface. For each interface that has units it is described for the registry key <interface>.<unit-name>. Note that this registry key is created or changed in effect of the operation. The register state reflects the process of unit altering. It becomes ready when the process completes.

All registers handled by the unit being altered unit are stopped and started again
The parameters register is one for all units of the given interface. One should avoid using it to modify multiple units in parallel. Otherwise its state will reflect the unit that was altered first.
When the register is signaled ready, that means that the unit is changed and started. This does not imply that the unit is fully operating. Some units might require additional time to connect to the hardware. Especially ones dealing with network connections.

Deletion

When an empty string is sent, the corresponding unit is removed. The register state reflects the process of unit deletion. It becomes ready when the process completes.

All registers handled by the unit are deleted

The unit registry key <interface>.<unit-name> is deleted.

PGM frame length

Real
[s]

any

The minimal length in seconds of the informational frame multicast server publisher. The frame length determines how quickly a client may synchronize itself with the server. The value set has a lower priority than the frame traffic limitation.

Direction	Description
Input	When sent, it changes the current setting. The initial frame length is determined by registry key PGM.FrameLength.
Output	When requested, the actual setting is returned.

PGM frame traffic limit

Real
[1/s]

any

The maximal traffic in bytes per second of the informational frame multicast server. The frame length determines how quickly a client may synchronize itself with the server. The traffic limitation influences only informational packets. The incremental data packets are not counted. Note also, that the protocol used by LabMap^® supports coalescing of the informational and incremental packets. That is, when an incremental packet is about to be sent and it is determined that an informational packet could be sent as well, both are merged in one packet. This optimization need to be kept in mind when the frame size is determined. Because in this case the data packet will be counted to the frame.

Direction	Description
Input	When sent, it changes the current setting. The initial frame length is determined by registry key PGM.MaxFrameTraffic.
Output	When requested, the actual setting is returned.

PGM group (IP address)

String

any

The group of a multicast server publisher. The group is an IP address of D class. The behavior of this register depends on its I/O direction

Direction	Description
Input	When sent, it changes a publisher's configuration or deletes it. The value of the input publisher name register is the name of the publisher to modify, the input port register contains the port number. When the port number is negative, the publisher specified is deleted. When the port is positive the publisher configuration is changed. In this case the published registers stay published if no error occurs.
Output	In this register the publisher's group is set. This happens when either the publisher is obtained through enumeration, i.e. by requesting the publisher name register. Or when either of the output registers group register, port register, configuration register is requested. In the latter case the current value of the output publisher name register is the name of the publisher. Use LabMapSetString to set publisher name register.

PGM published handle

Integer

any

The number of a published register.

Direction	Description
Input	When sent this register and the input publishing period register change publishing status of a register. The input publisher name register is the name of the publisher for which a registers should be published or unpublished. When the value of the input publishing period is negative the register specified by the value of the register becomes unpublished. Nothing happens if there is no such register published. When the value of the register is 0, then all registers become unpublished. When the value of the register denotes an existing register and the period specified is non-negative then the register specified becomes published with this period.
Output	This is used for enumeration of published registers. The output publisher name register specifies the publisher. Use LabMapSetString to set the output publisher name register or request it to enumerate existing publishers. When output published handle register is requested, the result is the next published register number. When there is no more published registers, the result is 0. If the value of the register is 0, then the result is the first published register or 0, when there is no one. When a non-zero value is set, the output publishing period register is set, when exists, to reflect the publishing period of the published register.

PGM publisher configuration

String

any

The configuration string of a multicast server publisher. The configuration string format is described above.

Direction	Description
Input	When sent, it changes a publisher's configuration The value of the input publisher name register is the name of the publisher to modify. All registers published by the modified publisher become unpublished if not specified in the new configuration.
Output	In this register the publisher's configuration is set. This happens when either the publisher is obtained through enumeration, i.e. by requesting the output publisher name register. Or when either of the output registers group register, port register, configuration register is requested. In the latter case the current value of the output publisher name register is the name of the publisher. Use LabMapSetString to set the output publisher name register.

PGM publisher name

String

any

The name of a multicast server publisher. Publisher names are case-insensitive. They can contain digits, letters and underline (_) characters. The behavior of this register depends on its I/O direction:

Direction	Description
Input	When sent it is immediately acknowledged.
Output	This is used for enumeration of existing publishers. When requested the current value is used as the starting point of the enumeration process. When there is a publisher with the name lexicographically greater than the name of the publisher specified by the register value, then it becomes the new register value. Otherwise the result is an empty string. When the current value is an empty string then the result is the name of the first existing publisher. When there is no publishers, the result is an empty string. When a publisher name is the result, the multicast group, port and configuration of the publisher are set into the output group register, port register, configuration register, correspondingly, if these registers exist. When no publisher as found these registers are set to error state. This register is also used for explicit requests for parameters of publisher. In this case the publisher name is first set into this register by using LabMapSetString. Then either of the output group register, port register, configuration register is requested. As the result their values are set to reflect the parameter of the publisher. When no publisher exists the existing output group register, port register, configuration register are set to error state.

PGM publisher port

Integer

any

The port of a multicast server publisher.

Direction	Description
Input	When sent, it changes a publisher's configuration or deletes it. The value of the input publisher name register is the name of the publisher to modify, the input group register contains the multicast group. When the port number is negative, the publisher specified is deleted. When the port is positive the publisher configuration is changed. In this case the published registers stay published if no error occurs.
Output	In this register the publisher's port is set. This happens when either the publisher is obtained through enumeration, i.e. by requesting the output publisher name register. Or when either of the output registers group register, port register, configuration register is requested. In the latter case the current value of the output publisher name register is the name of the publisher. Use LabMapSetString to set publisher name register.

PGM publishing period

Integer

any

The period of a published register. The period controls coalescing of frequent register state changes, when they are published as described above.

Direction	Description
Input	When sent this register and the input published register number register change publishing status of a register. The input publisher name register is the name of the publisher for which a registers should be published or unpublished. When the value of the register is negative the register specified by the value of the input published register number becomes unpublished. Nothing happens if there is no such register published. When the value of the input published register number is 0, then all registers become unpublished. When the value of the input published register number denotes an existing register and the period specified is non-negative then the register specified becomes published with this period.
Output	In this register the publisher's period is set. This happens when either the register is obtained through enumeration, i.e. by requesting the output published register number. Or else when the register is requested. In the latter case the current value of the output published register number is the number of the published register which period is to query. Use LabMapSetInt to set the output published register number.

Polling interval Real Input LabDiCom.dll The polling interval used for the DiCom 4000 interface. When set to zero no polling is made. Otherwise the interface tries to get the actual information from the device in the specified intervals. The state of the register reflects the I/O communication state. It goes off-line when an I/O error occurs.

Queued requests Integer Output any
with device units The value, when requested returns the number of requests pending in the queue of the register's unit queue. Note that when this register is queried manually rather than periodically, it would respond even if the unit is busy. The value is queried asynchronously to the unit thread.

String,
Integer

Input,
Output

any,
with device units

These registers are used for enumeration and matching of the device registers. Two combinations are used:

Direction

Type

Description

Input

String

The register of this type defines the pattern of the register name to search for. The pattern has the syntax of the register name:

<description> [ [<unit> [<parameters> [....<parameters>]]] ]

Here <description> is the register name part before square brackets. It is ignored when does not match one of the following virtual registers:

Parameters register
Restart register
This register
Unit name register

The field <unit> matches the unit name, case insensitive. The <parameter> fields match the unit parameters. Depending on the interface matching can be more or less intelligent. The default implementation matches the parameters case-insensitive with chains of spaces equivalent to one space. The fields <unit> and <parameter> can be separated by delimiters: spaces, colons and points. For single unit interfaces, the <unit> field is set empty.

When a value is send to this register it changes the pattern.

Output

Integer

When requested this register starts unit registers lookup. The process starts with the register number following the initial value of the register. When a register is found that matches the pattern, its number becomes the new value of the register. Otherwise the new value is 0. Setting the register to 0 and requesting it until the result is 0 allows to enumerate all the registers of the interface and the particular unit matching the specified pattern.

When requested with no pattern register existing, the result is error register state (StatusRRRNotAvailable).

Response time Real, s Output any When requested the result is the response time of the interface dispatching thread, i.e. the time require to post a message to the thread and get a response to it.

Restart Integer Input any When a value is sent to the register the corresponding interface is restarted. For instance, when the register is associated with the LabMap.dll interface, then sending any value to the register would restart the interface. The register associated with the LabMap.dll resets all interfaces as if the Soft Reset menu item were selected on the main panel.

Tasks statistics String Output LabMap.dll The register, when requested will contain the statistics of the internal tasks. The statistics is a string containing for each thread a description consisting of the task name followed by tabulation (ASCII 09₁₆) and the information text of the current task state. The task descriptions are separated by new line character (ASCII 0A₁₆).

Temperature Real Output LabPLU.dll The measured temperature (the hardware unit shall be set to °C)

Unit

String

Output

any,
with device units

This register is used together with the parameters register to modify device units of the interfaces which have such. It can also be used to enumerate the existing units. When requested the result is the unit name lexicographically greater than the current register value. When there is no such unit, the result is an empty string.

5.3. User-defined registers (LabUser)

The hardware independent interface offers an ability to define registers maintained by an application. Registers with LabMap.dll specified as the handler (>Map>) are considered to be user-defined. A user application may get and set values of such registers using standard technique. User defined registers can be sent and requested. In this case ending of the sent or request operation lies on the user application, which can do it either by setting a value or by setting error (LabMapSetError). This feature can be used for implementation of interfaces provided by the user application. For instance, a register can be defined for some complex operation involving some set of other registers and I/O. Sending a new value to the register would initiate the operation by a thread in a user application (see LabMapWaitForUpdate). Upon operation completion the thread would call LabMapSetError or LabMapSet{Int|Real|String}[Ex] which will end the pending state of the register.

Alternatively one can use the LabUser.dll specified as the handler (>User>) for the registers where no reaction is required. The send and request queries are immediately satisfied. This way one can implement shared variables not related to any specific hardware. Such variable is assigned using an appropriate LabMapSendInt[Ex], LabMapSendReal[SI][Ex], LabMapSendString[Ex] function.

5.4. Remote access interface (LabNet)

The remote access interface is provided by the LabNet.dll.

Server configuration. The server part is responsible to accept connections from clients. It is controlled by the registry keys MaxConnections, HostsAllow, HostsDeny and Port. MaxConnections limits the number of simultaneously connected clients. The server part is not started when MaxConnections is 0. Note that this is the default. HostsAllow and HostsDeny are used to prevent unsanctioned access. The key Port specifies the TCP/IP port used to accept the connections from the clients.
Client configuration. The client part may maintain more than one connection to remote servers. It is also possible to establish several connections to same server. Each connection to a remote server is indicated by server's nick name. The nick name is a case sensitive text string indicating the remote server. For each nick name (server) the following registry keys should be defined: Server.<Host>, Port.<Host>, where <Host> indicates the nick name of the remote server. The key Server.<Host> contains the address of the remote server to connect to. The key Port.<Host> specifies the TCP/IP port used for the connection.
Remote register configuration. Remote registers are handled by the LabNet.dll (>Net>). The request policy of a remote register has the following meaning. Upon request and input registers are updated from the server side. The frequency the updates are sent to the client is limited by the RemotePollLimit registry key. On change registers are updated not oftener than specified. Each registers are updated as specified no matter whether their state is changed.

The name of a remote register name may end with additional properties specification put in square brackets. For instance, register 2810 could be defined as:

>Net>[m/s:m/s:km/h]O:R:0:100:-1:-1:Speed [2810.RRR]

Here the additional properties specification is [2810.RRR]. It has the following format:

[<Register>.]<Host>

<Register> specifies the register number (based) on the server side. This allows to map a remote register to any desired register of the remote server. In the given example both registers on the client and server sides have same number, so '2810.' could be omitted. <Host> defines the nick name of the remote server. In our example it is 'RRR'. When this part is missing the nick name is assumed to be empty. Each unique nick name indicates a separate connection to some remote server. For each such name a virtual input string register named 'Host [<Host>]' shall be declared (host name register). In our example it should have the name Host [RRR]. This register is initialized with the contents of the registry key Server.<Host>. It always contains the name of remote server. A send operation over this register causes reconnection to the designated remote server. An off-line error on the register indicates that the remote server is currently off-line. Note that there is no need to manually reconnect to the remote server on an error, because LabNet.dll does it automatically. So the connection is restored as soon as possible. The remote host registers can be browsed from the client side using the host number register (see).

The remote access interface has an extended API supporting temporal connections to remote hosts. An application may connect to a remote host, enumerate the registers of the remote host, map remote host registers through the local ones. When a connection is closed all registers related to the connection are automatically removed. The following functions are provided by LabNet.dll (the function prototypes are declared in LabNet.h):

5.4.1. LabNetConnect

int LabNetConnect
(
   unsigned   * Index,
   const char * HostName,
   unsigned     TimeOut);

This function creates a new connection to the remote host identified by the parameter HostName. It can either a name or IP address followed by a list of modes placed in round brackets. For instance: host1.hall2.myplant.com (ro, sync). See host name register for available modes. The list of modes can be omitted. A connection is represented by a set of registers used to communicate with the remote host. The registers are created as temporal. They are removed upon closing the connection (see LabNetDisonnect). The parameter Index is the pointer to the connection index. The returned upon success value should be used in all consecutive calls related to the connection. Note that registers associated with a new connection are initially accessed using LabMapRegAccess. This ensures that the application calling LabNetConnect may use the registers. Therefore you should be careful when a full access (rw mode) is established to a remote host. Such connection may distort applications running on the remote host, because any access gained to either to the system as a whole or to a network register will propagate to the remote host. ResRRRTimedOut is returned when the remote host connection is closed due to a time-out. ResRRRAccessDenied indicates a refused connection or an illegal host name. ResRRRNoHandlesLeft is returned if there is no free registers left. Other errors indicate a system fault.

5.4.2. LabNetConnectEx

int LabNetConnectEx
(
   unsigned   * Index,
   const char * HostName,
   unsigned     TimeOut,   unsigned   * HostHandleNo,
   unsigned   * RegStatusHandleNo,
   unsigned   * RegNameHandleNo,
   unsigned   * RegNumberHandleNo,
   unsigned   * RegUnitHandleNo);

This function is similar to LabNetConnect except that it additionally allows to specify the desired number of the temporal registers which will be created for the connection. The additional parameters are pointers to the desired registers numbers. When the values of these registers are valid and unused register numbers, they will be used for the corresponding temporal registers. Otherwise the function will choose another number and it will replace the number pointed by the parameter.

5.4.3. LabNetDisconnect

int LabNetDisconnect
(
unsigned Index
);

This function closes a connection opened by LabNetConnect (see). The connection is identified by the parameter Index (see LabNetConnect). ResRRRWrongHandle is returned if the index is illegal. All registers associated with the closed connection are removed.

5.4.4. LabNetGetConnectionInfo

int LabNetGetConnectionInfo
(
   unsigned   Index,
   unsigned * HostHandleNo,
   unsigned * RegStatusHandleNo,
   unsigned * RegNameHandleNo,
   unsigned * RegNumberHandleNo,
   unsigned * RegUnitHandleNo
);

This function requests the numbers of special registers associated with the connection identified by the parameter Index (see LabNetConnect). The special registers are automatically created upon establishing the connection. They can be used for browsing the remote host registers (see host number register). ResRRRWrongHandle is returned if the index is illegal. The registers are returned via pointers. Any of the pointers can be zero if the corresponding register number is not required.

5.4.5. LabNetGetHandleInfo

int LabNetGetHandleInfo
(
   unsigned     Index,
   unsigned   * HandleNo,
   unsigned   * Status,
   const char * Name,
   unsigned     NameLength,
   const char * Units,
   unsigned     UnitsLength
);

This function searches for a remote host register and requests information about it. The connection is identified by the parameter Index (see LabNetConnect). ResRRRWrongHandle is returned if the index is illegal. The parameter HandleNo is the pointer to the remote host register number. It shall be initialized with the number preceding the search starting point. The function finds the first remote host register with the number greater than HandleNo points to. To find the first remote host register one may specify zero. ResRRRNoHandlesLeft is returned if there is no remote registers with numbers greater than the value HandleNo points to. Otherwise, the number of the found register is returned via HandleNo. The remaining parameters are used only if a register was found. All of them can be zero if no information required. The parameter Status accepts the remote host register status (see LabMapGetStatus). The parameter Name accepts the remote host register name. The parameter NameLength specifies the length of the buffer Name. The parameter Units accepts the input measurement units of the remote host register. The parameter UnitsLength is the length of the buffer Units. ResRRRAccessDenied is returned if the application has lost access to the special registers associated with the connection. ResRRRTimedOut and ResRRRNotHandled may indicate connection problems.

5.4.6. LabNetMapHandle

int LabNetMapHandle
(
   unsigned     Index,
   unsigned   * HandleNo,
   const char * Name,
   unsigned     Status,
   unsigned     TimeOut,
   unsigned     Each,
   const char * Units
);

This function maps a remote host register. It creates a local remote register mapped to the remote register. All operations over the local register were performed on the remote one via the LabNet interface. The connection is identified by the parameter Index (see LabNetConnect). ResRRRWrongHandle is returned if the index is illegal. The parameter HandleNo is the pointer to a remote host register number to be mapped. The number of the newly create local register is stored into HandleNo. The parameters Name, State, TimeOut, Each and Units have same meaning as for LabMapCreate (see). The parameter Name can be specified as zero if the name is no matter, The values of the parameters Name, Status and Units are usually obtained using LabNetGetHandleInfo. The bits:

HandleDefaultTimeout, HandleNoTimeout and the parameter TimeOut
HandleOnChange, HandleUponRequest and the parameter Each

should be set according to the desired timings policy of the newly created register. The parameter TimeOut specifies the time limit (ms) for I/O operations with the local register if neither HandleDefaultTimeout nor HandleNoTimeout is set. The parameter Each is required for output registers if either HandleOnChange is set, or HandleUponRequest is clean. The bit HandleNewFromRRR can be added to automatically enable callbacks for the new register. Note that the created register will be temporal, exclusive, accessed by the application called LabNetMapHandle. It will be removed by LabNetDisconnect. ResRRRNoHandlesLeft is returned if no free registers are available. ResRRRWrongPolicy is returned if the specified register policy is illegal. Other return codes indicate a system fault.

5.5. DiCom 4000 interface (LabDiCom)

The interface to the exhaust gas analyzer device AVL DiCom 4000 is provided by the LabDiCom.dll. The registers handled by the interface shall have names ending with a numeric code in square brackets. For instance:

>DiCom>O:R:0:0:-1:-1:CO [340]

Here the register is attached to the DiCom's measurement value 340 (in this case it is CO in % of volume). The code is device specific, refer to AVL documentation for the list of codes and their meaning. All DiCom registers are output ones except for one named polling interval used to control the communication with the device. The serial port used for the communication is specified by the registry key DiCom.Port. The port should have the following settings (Start / Settings / ControlPanel / Ports):

Baud rate: 9600

Data bits: 8

Parity: none

Stop bits: 1

Flow control: none

Pin connection for the serial cable:

Note that the AVL DiCom 4000 device responds with data only during a measurement. The data contain only the values related to the measurement. During self test and in the configuration menu the device responds with NAK (signaling that data are not ready). Note also that many values are measured in non-SI units (like % of volume etc.). Please, refer AVL documentation for details.

5.6. Remote control interface (LabRC)

The interface to the Volltronic's remote control device is provided by the LabRC.dll. The serial port used for the communication is specified by the registry key RC.Port. The ports should have the following settings (Start / Settings / ControlPanel / Ports). The interface recognizes three registers by their names.

Command (output, string). The register accepts the device input (upon a key hit). The encoding is the following: STX ( <code> ETX <sum>. Here <code> denotes the code of the pressed key. It is always single character in the range '0'..'9','A'..'N'. <sum> is one character check sum calculated as xor of the sequence ( <code> ETX.
Code (output, integer). The register accepts the upon a key hit the scan code of the pressed key (refer to Volltronic documentation for scan codes).
Text (input, string). The register when sent causes printout on the device's LCD. The string is encoded as follows:

Pos.1 String format Meaning

'0'..'7' n <text> Here n is the line number encoded as '0'..'7' ASCII. <text> is sent to the LCD. Texts larger than 16 characters are wrapped to the next line. Wrapping of the last (8th) line of the display scrolls its contents up.

STX STX n <text> ETX <sum> Here n is the line number encoded either as '0'..'7' ASCII or as 0..7 ASCII. <text> is sent to the LCD. <sum> is one character check sum calculated as xor (it is ignored). Texts larger than 16 characters are wrapped to the next line. Wrapping of the last (8th) line of the display scrolls its contents up.

The device should be configured once before use (see configuration menu->system of the device). The following device parameters should be set:

SysKeyFkt should be set to FF;
MainProg should be set to 33.

5.7. AK interface (LabAK)

The interface to AK devices is provided by the LabAK.dll. Up to 8 AK devices can be simultaneously controlled. The serial or TCP/IP ports used for the communication are specified in the AK software configuration. AK registers are handled by the LabAK.dll (>AK>). The request policy of an AK register has the following meaning. Upon request registers are explicitly requested (see LabMapSend and LabMapRequest). On change and each registers are polled by the AK software. Note that no attempt to filter incoming data is made. I.e. on change is an equivalent of each. The name of an AK register name shall end with the additional properties specification put in square brackets. For instance, the register 3010 could be defined as:

>AK>[mg/l:mg/m³:mg/m³]O:R:0:100:-1:-1:Soot density [AKON.2.K0]

Here the additional properties specification is [AKON.2.K0]. It has the following format:

[!] <Tag>.<Port>[.K<Host>] [=<Field>] [,<Tag> [=<Field> [,<Tag> [=<Field>...]]]]

The four character <Tag> specifies the AK command associated with the register, like SMAN, SREM etc. The <Port> is the number of the virtual AK port used for the communication. The AK software maps the virtual ports to the hardware COM and TCP/IP ports. See AK software configuration for further information. The optional combination .K<Host> defines the beginning of the AK command sent to the device. Usually it is K0, refer to the AK device specification for further information. When missing, no Kn prefix is used. The optional specification =<Field> indicates the number of the field where the value should be taken from or placed to. It is possible to associate a register with several AK commands. For instance:

>AK>[km/h:km/h:km/h]O:R:0:100:-1:-1:Current speed [AWRX.1.K0=1,AWRT=2]

Here the register is associated with two AK commands: AWRX and AWRT. When a response to AWRX comes, then the value of the register is updated from the first data field. When a response to AWRT comes, then the value of the register is updated from the second data field. The number of the commands associated with a register is not limited. The fields are numerated from 1. Fields are separated by blank characters. When no field specified the whole response text is taken (decoded). One can have both a register with no field specified and an arbitrary number registers associated with different fields of the same AK command. Fields can be skipped, i.e. remain not associated with no register. If a response does not contain some fields the corresponding registers are not set. Fields can be applied to both output and input registers. The register associated with the first defined field of a command controls the policy of the AK command. It is a controlling register. For instance, if the register 2810 is associated with the field 1 of the AK command AWRX, and the register 2820 is associated with the field 2 of same command:

2810: >AK>[km/h:km/h:km/h]O:R:0:100:-1:-1:Current speed [AWRX.1.K0=1]2820: >AK>[rpm:rpm:rpm]O:R:0:100:-1:-1:Motor revolutions [AWRX.1.K0=2]

then the policy of the register 2810 becomes the policy of the command AWRT. The same register governs the command direction too. I.e. if it is an input register then the values of the fields are sent to the AK host. If it is an output register, then the values from the AK host are used to set the registers associated with the fields. Note that <Port>[.K<Host>] is only specified for the first AK command associated with the register. This command is used when the register is requested (LabMapRequest) or sent (LabMapSend). The type of the controlling register is used to encode and decode the AK commands:

Type	Input controlling register (sent)	Output controlling register (received)
Integer	A send request (LabMapSendInt) sends the [K<Host>] <value> command to the AK device. Here <value> is the register's value in ASCII format. The device responds with the acknowledge command. The error character of the acknowledge telegram defines the status of the register (see LabMapSetError).	A value request (LabMapRequest) sends the [K<Host>] command to the AKdevice. The device answers with <error> <value>. The character <error> of the acknowledge telegram defines the status of the register (see LabMapSetError). <value> is decoded as an integer integer and the result stored into the register if no field specified. Otherwise the specified field of <value> is decoded. The decoded text may start with characters other than digits or signs, so #?-24 is allowed and decoded as -24. Only when the text cannot be interpreted as a number, the value zero is set.
Real	A send request sends the [K<Host>] <value> command to the AK device. Here <value> is the register's value in ASCII format. The device responds with the acknowledge command. The error character of the acknowledge telegram defines the status of the register (see LabMapSetError).	A value request (LabMapRequest) sends the [K<Host>] command to the AK device. The device answers with <error> <value>. The character <error> of the acknowledge telegram defines the status of the register (see LabMapSetError). <value> is decoded as an floating-point value and the result stored into the register if no field specified. Otherwise the specified field of <value> is decoded. The decoded text may start with characters other than digits or signs, so #?-24.7e+1 is allowed and decoded as -2.47e+2. Only when the text cannot be interpreted as a number, the value zero is set.
String	A send request sends the [K<Host>] <value> command to the AK device. Here <value> is the register's value. Make sure that the value does not contain non-printable characters, for they may confuse the AK device. The device responds with the acknowledge command. The error character of the acknowledge telegram defines the status of the register (see LabMapSetError).	A value request (LabMapRequest) sends the [K<Host>] command to the AK device. The device answers with <error> <text>. The character <error> of the acknowledge telegram defines the status of the register (see LabMapSetError). <text> is stored into the register if no field specified. Otherwise the specified field of <text> is stored. When <text> is put in quotation marks, the marks are stripped out before storing.
Block	Not supported	Not supported

Note that more than one register can be associated with the same AK command. For instance if registers 2000 and 2001 were declared as following:

>AK>[km/h:km/h:km/h]O:R:0:100:-1:-1:Current speed [AWRX.1.K0=1] >AK>[rpm:rpm:rpm]O:R:0:100:-1:-1:Motor revolutions [AWRX.1.K0=2]

and the controlled register of AWRX is an output register. Then the response from the AK server:

AWRX 0 24.0 800.23

would set the register 2000 to 24.0 km/h and 2001 to 800.23 rpm. If a response does not contain some fields the corresponding registers are not set. In contrary to this if the response contains an error code it is reflected by all the registers associated with the command. The actual value can be requested using any register associated with the command for those the command appears first in the command list in square brackets. If the controlling register is input then the data field of the command will contain the value of the register as described above. When the register is associated with the whole command, the data field of the AK command sent to the host contains only the register value. Otherwise it also contains the values of all registers associated with the command separated by space and following the order of their fields. The actual values can be sent to the AK host using any of the registers associated with the command for those the command appears first in the command list in square brackets.

Treatment of AK errors. The AK status code 1-9 when appears in an AK response causes the corresponding registers to be set into the error state with the status numerically equal to the AK code. For example, the response:

AWRX 3 24.0 800.23

will set the status of all registers depending on the fields of the command AWRX to 3. This behavior can be undesired. When the exclamation sign ! appears in before the four character <Tag> in the declaration of the controlling register then the status of the corresponding AK command is ignored for all registers depending on the response to <Tag>. For example:

>AK>[mg/l:mg/m³:mg/m³]O:R:0:100:-1:-1:Soot density [!AKON.2.K0]

This will turn of error handling for AKON on the port 2.

5.8. NI-CAN interface (LabNICAN)

The NI-CAN interface is provided by the LabNICAN.dll. An adapter card by National Instruments supports up to 2 CAN ports. They can be used simultaneously. The name of a NI-CAN register shall end with additional properties specification put in square brackets. Note that the CAN adapter card provides each incoming data frame with the time stamp, which becomes the time stamp of the corresponding LabMap^® register as the data are read from the buffer. A NI-CAN register could be defined as:

>NICAN>[::]O:I:0:-100:514:295:5 [Port1 ID=5 length=7 p=0123456]

Here the additional properties specification is [Port1 ID=5 length=7 p=0123456]. It has the format <board>.[<parameter> [<parameters>...]. Parameters can be separated by spaces, colons and points. Each parameter has the format <name>=<value>. In the given example <board> is Port1, the parameters are ID=5, length=7 and p=0123456. <board> indicates the name of a CAN adapter's port. For each board name there should be a string registry key named NICAN.<board> containing a description of the board. In the given example there should be a registry key named NICAN.Port1. The description of the board specifies the adaptor type, location, number of CAN ports, their baud rates, operating modes and memory used for buffered I/O. The following table provides the list of the valid register parameter names (case insensitive):

Name

Abbreviations

Description

Default

and

a, andmask

See and-mask

all bits set

binary

b, bin

See binary

non-binary

double

See double

single

extendedid

extended, extID, extID, ext, e

The value is either 0 or 1. The value zero indicates that the arbitration ID has standard 11-bit size. The value one is used for extended 29-bit arbitration IDs

The value is the CAN arbitration ID. Each register should have a unique arbitration ID. It is a based unsigned integer or the wild-card *. When the CAN arbitration ID is specified as *, i.e. id=*, the register works in a special way depending on the I/O direction. The unsolicited frames sent and received by the special registers with id=* require queues to keep the frames. Due to design of underlying National Instruments software the buffer sizes cannot be provided by the buffer parameter as in the case of normal registers. It is set in the registry. See NICAN<port>.ReceiveQueueSize and NICAN<port>.SendBufferSize.

length

len, l

The length of the data field in bytes. CAN-bus messages may contain up to 8 bytes data. It is a based unsigned integer.

o, ormask

See or-mask

permutation

p, byteorder

87654321

shift

<<, >>

See shift

signposition

sign, signat, signplace, signpos

N/A

single

See single

single

status

stat, state

CAN bus general status as responded by a CAN controller. When specified no other parameters are allowed. Only output integer registers are allowed. When requested the result is the status of the CAN controller:

Value	Meaning
0	Normal state, on-line
1	Warning, some errors were detected, but the controller is still on-line
2	Error. The controller has switched off-line after multiple errors
3	The controller is off-line

N/A

xor

See xor-mask

The input NI-CAN registers are used for sending CAN data frames. The outgoing data are post-processed as follows:

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0. If a sign position specified then signed numbers are represented in the binary complement format.
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
The permutation is applied to the buffer bytes
The first length bytes of the buffer contents are sent.

The 'upon request' and 'on change' output registers accept unsolicited CAN data frames. For the 'on change' registers the data are received only if they differ from the previously received data. The 'upon request' registers accept any data. A call to LabMapRequest causes sending a CAN remote frame. The 'upon request' and 'on change' registers can be used when the communicated CAN device sends the data frames either in arbitrary manner or in response to a CAN remote frame. On contrary to this the 'each' registers accept the data periodically. They accept all data frames regardless to their content. The hardware watchdog is configured to ensure that the data come within the specified time interval (1.5 of the value of the parameter policy). One can use such registers the CAN device sends data frames periodically. The incoming data are pre-processed as follows:

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0.
The permutation is applied to the buffer bytes
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
Either the buffer is treated as an unsigned number (for numeric registers) or the first length bytes of the buffer contents are used (for string registers). If a sign position specified then the number is assumed to be in the binary complement format.

A description of an CAN adapter card supported by the interface has the following syntax:

<port>:<baud>[:<send>[:<receive>]]

Parameter	Description
<port>	Is the port number 1..2. An adapter card supports up to two ports.
<baud>	The baud rate (kBaud). It is a based unsigned integer.
<send>	The size of the send buffer in CAN telegrams. It shall be greater than 20. It is a based unsigned integer.
<receive>	The size of the receive buffer in CAN telegrams. It shall be greater than 20. Note that the buffer should be big enough to buffer all incoming telegrams without data loss. It is a based unsigned integer.

Here is an example of a board description:

0:500:100:200

5.9. PLU 401 interface (LabPLU)

The interface to the exhaust gas analyzer device Pierburg PLU 401 is provided by the LabPLU.dll. The registers handled by the interface shall have one of the following names: Density (measured by the device), Temperature (measured by the device). The serial port used for the communication is specified by the registry key PLU.Port.

5.10. OPC interface (LabSPS)

The OPC interface is provided by the LabSPS.dll. It has the name SPS. The registry key SPSServer specifies the name of the OPC server. The registry key SPSHost gives the name of the network host running the OPC server. The registry key SPSID specifies the identifier of the server (32 hexadecimal figures). The registry key SPSRefreshRate determines how often the server variables should be polled (in ms). The name of a SPS register shall end with additional properties specification put in square brackets. A register could be defined as:

>SPS>[::]I:I:0:0:-1:-1:Feedback [type=I4 pref=WriteGroup name=M12ADWORD1,1]

Here the additional properties specification is [type=I4 pref=WriteGroup name=M12ADWORD1,1]. It has the format of a space separated list of tokens. Each token consists of the name and the string value assigned to it. The following table indicates the list of names that can be used for register properties configuration:

Name Abbreviations Description Default

name n, nam The name of the variable. This string is added to the name prefix to build the name of the OPC variable. N/A

prefix p, pref The prefix used for the name. The name of the OPC variable associated with register is built as a concatenation of the prefix and the string given for the name parameter. The string <prefix> given for the prefix is used for search for the registry key SPS<prefix>. The value of the key is used as the prefix. In the given above example (pref=WriteGroup name=M12ADWORD1,1) the name of the register will be DP:[CP_L2_1:]Slave002M12ADWORD1,1, where DP:[CP_L2_1:]Slave002 is the value of the registry key SPSWriteGroup. empty

type

t, typ

The type of the OPC variable associated with the register. The following data types are currently supported:

Type	Notation	Abbreviations
bit	boolean	bool, BOOL
unsigned byte	unsigned1	u1, U1, UI1, uchar
signed byte	int1	i1, I1, char
unsigned short	unsigned2	u2, U2, UI2
signed short	int2	i2, I2
unsigned int	unsigned4	u4, U4, UI4
signed int	int4	i4, I4
float	real4	r4, R4
long float	real8	r8, R8

N/A

Due to the nature of the OPC the request policy have no effect on the output registers.

5.11. Virtual interface (LabVirt)

The Virt interface is provided by LabVirt.dll. This interface gives an ability to calculate registers out of other register values. Such a register could be defined as:

>Virt>[::]I:I:0:0:-1:-1:Sum [$1200 + $2810]

Here $1200 + $2810 is the expression used to evaluate the register. The expression in square brackets can be preceded by the trigger specification (see register policy)

5.11.1. Types, literals, register values and time stamps

Three data types are supported: integers (64-bit), dimensioned real (floating-point 64-bit) numbers of some measurement unit, and strings. Literals and variables are terms of the expression:

Integer literals are specified in form a based integer number. For instance, 23 and 16#FFF# are integer literals.
Real literals can be specified as a number with point and/or exponent part. For instance, 2.0. Optionally a real literal may contain the unit specification in square brackets: 2.0 [°C].
String literals can be specified using quotation marks or apostrophe. For instance: "This string contains "" marks". Here doubled quotation marks are used to represent the quotation marks within the string body. With apostrophes it could be 'This string contains " marks'.
Register name literals are specified in <> brackets. For example: <Velocity>. The register name is matched case-insensitive. The register configuration part of the name in square brackets [] does not participate in the match. Note also that register names can be ambiguous. When matched register name literal is equivalent to the integer register number.

Real and integer are numeric types. There are several operations that accept any numeric types as arguments (no matter real or integer). For such operations when one operand is real and another is integer, the integer operand is converted to a real of unspecified unit. This allows an operand to gain an appropriate unit from the context.

Accessing the register data:

$<number>.or $<<name>> The value of any register can be accessed like $2810. Here 2810 is the number of the register. The second variant deploys the register name instead. For example $<Velocity>.
@<number>.or @<<name>>. The time stamp of a register can be acquired like @2810. The time stamp has the real type, it is measured in seconds from the operating system start.
%<number>.or %<<name>>. The register update flag is specified as %2800. The update flag is non-zero if the register was updated since last access to the flag. Updating is any action of setting register's value or state, even if the result of that action does not change the value or the state. Note that the update flag of the same register can be independently requested several times, like %2800+%2800.

All calculations with real types are made in SI units. This may sometimes lead to surprises like in the expression 1[°C]+1[°C], which results in 548.3K=275.15°C rather than 2°C. When the measurement unit of a real is not explicitly specified, an appropriate SI unit is chosen from the context. Therefore the expression 1[°C]+1 is treated 1[°C]+1[K] , which gives the result 274.15K=2°C. The hardware unit of a virtual register may differ from the corresponding SI unit. In this case the register keeps the value in that unit. Yet it has no influence on the way the register value is evaluated, which as it was said, always happens in SI units.

Computation errors, like zero divide etc, lead to setting the register into an erroneous state. So its value remains unmodified.

5.11.3. Blanks and comments

Space, tabulation (HT), linefeed (LF) and carriage return (CR) are blank characters. They can be used to separate lexical tokens of an expression. Comments may appear everywhere one can put a blank character. There are two types of comments:

The comments introduced by double forward slash // ends till the first appearance of either a linefeed or a carriage return character;
The comments introduced by forward slash and asterisk /* are ended by the first appearance of */. The comments of this kind cannot be nested.

5.11.4. Identifiers

The following identifiers are predefined:

Name(s)	Type	Meaning
`Clock`, `T`	Real [s]	The current time stamp. I.e. number of seconds passed from the operating system start. For triggered expressions the time stamp is one of the triggering event.
`Pi`	Real	π = 3.14...
`Value`	Of the trigger register	The value of the register triggered evaluation of the expression (see register policy)
`Size`	Real	The size of the currently used log file in bytes. The value is undefined if the on-line log plug-in is not present

5.11.5. Prefix operations

Prefix operations are applied to one argument. Name of the operation is placed before the argument. For instance, sqrt 5.0. Here sqrt is the name of the operation that calculates square root. Brackets are not required. The following prefix operations are supported:

Operation Name(s) Operand Result Example

Logical not !, not Integer Integer !0 results in 1

Unary plus + Numeric Numeric +45.0

Unary minus - Numeric Numeric -45.0

Arccosine arccos Dimensionless real Dimensionless real arccos 0.5

Arcsine arcsin Dimensionless real Dimensionless real arcsine 0.5

Arctangent arctan Dimensionless real Dimensionless real arctan 1.0

Conversions of bit fields

bits

Integer,
String

String,
Integer

Integer to string. bits 16#353433323130#. The result is a string. The string is evaluated as follows. The first 8 low order bits of the argument is the first character of the result, with the ASCII code equal to the bits. The second 8 bits is the second character etc. The process of conversion stops when remaining high order bits are all 0. In the example given, the result is "012345".
String to integer. bits "012345". The result is an integer. It is defined as an operation reverse to the integer one. I.e. the first character of the string determines the first 8 low order bits of the result. Thus for any integer x, x = bits bits x. Therefore in the given example the result is 353433323130₁₆=58498313498928. When the string argument is longer than 8 characters, it is truncated to exactly 8 character length first.

Conversion to character char Integer String char 35. The result is a string containing single character, which ASCII code equals to the argument. In the given example the result is the string "#". If the argument is greater than 255, the higher order bits are truncated.

Cosine cos Dimensionless real (rad) Dimensionless real cos 80 [°]. Note that the argument is in rad, so when degrees are used it should be explicitly specified as it done in the given example.

Differential operator d Real Real dT. The differential operator returns the difference between the current and the previous values of the argument. When calculated first time it is not defined. In the given example the argument is T, i.e. system clock. The operator d can be used for approximation of differentials. For instance, d$2810/dT approximates the differential of the register 2810.

Delay delay Numeric Numeric delay $1810. The delay operator returns the previous value of the argument. When calculated first time it is not defined. The delay statement can be used to simulate memory and build digital filters. Let U_n indicates the value of a signal now. Then U_n-1 can be obtained as delay U_n, U_n-2 is then delay delay U_n, etc. Thus the differential operator d can be built using the delay operator: d$1810 is an equivalent to $1810 - delay $1810. A multi-point mean window can be built using the delay operator. For example a four-point mean of the register 1810:
($1810 + delay ($1810 + delay ($1810 + delay $1810))) / 4

Exponent exp Dimensionless real Dimensionless real exp 0.1

Conversion to real real,
float Any Dimensionless real real "4.5". The argument real of can be of any type. It is converted to a floating-point number. In the given example it is a string to convert.

hh:mm:ss hourminsec,hhmmss Real in s String hourminsec sum dT. The operation returns a string obtained from a real argument in s. The result is the number of seconds in the format hh:mm:ss. Where hh is the hour 00..23, mm is the minutes 00..59 and ss is the seconds 00..59. Days are truncated. Negative arguments are treated as number of seconds to the next hour boundary. In the given example the system time is integrated and then represented in the hh:mm:ss format.

IEEE 754

ieee

String,
Real

Real,
String

When the argument is real, the result is 8-character length string of IEEE 754 representation of the argument. When the argument is string, the result is a corresponding dimensionless real. For a string argument, the length of the string must be at least 2 characters. Otherwise the result is set as undefined. The byte order in both cases is low-endian. That means that the least significant bits of the mantissa are stored in the first byte of the string. The last byte contains the number sign and the exponent bits. The format is as follows:

Bit
Byte 8 7 6 5 4 3 2 1

1 M₈ M₇ M₆ M₅ M₄ M₃ M₂ M₁

2 M₁₆ M₁₅ M₁₄ M₁₃ M₁₂ M₁₁ M₁₀ M₉

3 E₁ M₂₄ M₂₂ M₂₁ M₂₀ M₁₉ M₁₈ M₁₇

4 S E₈ E₇ E₆ E₅ E₄ E₃ E₂

The mantissa of the number is 1.M_n...M₁. The exponent is E₈...E₁ binary, with 127 bias. The length of the mantissa is determined by the length of the string argument.

Conversion to integer int,
integer Any Integer int 4.0. The argument is converted to an integer number

Natural logarithm ln Dimensionless real Dimensionless real ln 8.0

Decimal logarithm log Dimensionless real Dimensionless real log 8.0

Maximum max Numeric Numeric max $2820. The max operator calculates the maximal value of the argument.

Two point mean mean Numeric Numeric mean $2810. The mean operator calculates the sum of the current and the previous values of argument. The sum is divided to two. One can built a three-point weighted mean as mean mean $2810. If mean operator is applied n times. Its result is a sum of n+1 consequent values of the argument weighted by the binomial coefficients divided by the number of points. The mean operator can be used for building integrators. For instance: sum mean ($2810 * dT) integrates the value of the register 2810 using the formula of trapeze.

Minimum min Numeric Numeric min $2820. The max operator calculates the minimal value of the argument.

mm:ss minsec,mmss Real in s String minsec sum dT. The operation returns a string obtained from a real argument in s. The result is the number of seconds in the format mm:ss. Where mm is the minutes 00..59 and ss is the seconds 00..59. Hours are truncated. Negative arguments are treated as number of seconds to the next hour boundary. In the given example the system time is integrated and then represented in the mm:ss format.

Exponent exp Dimensionless real Dimensionless real exp 0.12

Conversion from character pos String Integer pos "#abc". The result of the operation is the code of the first character of the argument. If the argument is empty then the result is zero. In the given example, the result is 35, which is the code of '#'.

Sine sin Dimensionless real Dimensionless real sin (1[rps] * T). Note that the argument is in rad, so when degrees are used it should be explicitly specified. In the given example, a sine generator is built using the operator sin. T is the current clock. The result is the sine signal of 1 Hz frequency (1 [rps] = 2π ·1 Hz).

Square root sqrt Numeric Real sqrt 2.0. When the argument is not dimensionless it shall have all powers even. For example like in: sqrt 2.0 [W²]. When applied to an integer argument, the result is dimensionless real.

Conversion to string str,
string Any String string 2.0 results in "2.0". When a numeric is converted the result is a string containing the number in ASCII format.

Qubic spline s<name> Real Real s<interpolated-F> $2810. The operator s<name> calculates a qubic spline over the argument. The name given in angle brackets is the name of the spline. In the given example it is Interpolated-F (case insensitive). There could be an unlimited number of splines. Each spline is defined by a set of points (x,y), where x is the value of spline argument and y is the corresponding value of the spline. The spline interpolates between points using qubic interpolation. The values outside the spline points are linearly extrapolated. Note that at least one point is required to have spline defined. Three additional input registers serve for definition of the spline points. They shall have names name.x, name.y, name.reset. Here name is the spline name. To define a spline point (x,y), one should send the value x to name.x, wait for the operation completion, then send the value y to name.y and wait for completion. This sequence is repeated for all points of the spline. The points can be set in any order. The register name.reset is used to delete all spline points. Note that the dimension of the spline argument must be compatible with the units of name.x. The dimension of the result is defined by the units of name.y.

Sum sum Any Any sum $2810. The result is the sum of the argument values. Usually sum is used for building integrators like sum ($2810 * dT), here the value of the register 2810 is integrated using the formula of rectangle. It also can be used for integers and strings. See also the infix operator sum which represents sum with reset.

Tangent tan Dimensionless real Dimensionless real tan 1.0. Note that the argument is in rad, so when degrees are used it should be explicitly specified.

Trim trim String String trim " test " results in "test". The operation trim removes spaces, tabs, line feeds, carriage returns and the nul-characters from the both sides of the argument.

Bitwise inversion ~, inv Integer Integer ~0 results in -1 (all bits set)

Undefined <?> Any Integer <?> $2810 results in 1 if the value of the register 2810 is undefined. The result of <?> is 1 if the argument has no defined value and 0, otherwise. The argument is usually the value of a register, that is undefined when either the register is in undefined state or has an error. However the argument can be any expression. For instance, the effect of the operation when can be tested using <?>.

Integer expression <int>,
<integer> String Integer <int> "$2810 > 10.0". The string argument is interpreted is an integer expression. The expression is compiled and then evaluated. The result of the evaluation is the result of the operation. In the given example the result of the expression is an equivalent to $2810 > 10.0.

Real expression <real>,
<float> String Real <real> $4000. The string argument is interpreted is a real expression. The expression is compiled and then evaluated. The result of the evaluation is the result of the operation. In the given example the value of the string register 4000 is evaluated.

String expression <str>,
<string> String String <string> ("$" & $4002). The string argument is interpreted is an integer expression. The expression is compiled and then evaluated. The result of the evaluation is the result of the operation. In the given example the value of the integer register 4002 is concatenated with the dollar sign. The result is evaluated as an string expression. It has the effect of taking a string value from the register which number is stored in the register 4002.

5.11.6. Infix operations

Infix operations are applied to two arguments. Name of the operation is placed between the arguments. For instance, 5.0 + 1. Here + is the name of the operation that calculates sum. The following infix operations are supported:

Operation Name(s) Left Operand Right Operand Result Example

Comparisons !=, /=,
>,
<,
>=,
<=,
=,
>< Any Same as left Integer $2810 != 10 [km/h]. One can compare two numeric or two string arguments. If one of the numeric arguments is real it should have units compatible with the units of another argument. Strings are compared lexicographically and the result indicates their relationship. The operation >< functions similarly to !=. Its result is always defined. If any of the arguments is undefined the result of is >< 1.

Multiplication ·, * Numeric Numeric Numeric 4.0 * 2.1. If one of the arguments is real the result is also real.

Remainder %, rem Numeric Numeric Numeric 45.0 % 5. If one of the arguments is real the result is also real. The arguments should have compatible units. The result inherits the units of the arguments.

Case insensitive comparison %= String String Integer " Xy" %= "xY" results in 1. The operation compares two strings. First spaces, tabs, line feeds, carriage returns and the nul-characters are removed from the both sides of the arguments. Then the rests are compared, but case insensitive.

Bit wise and &, and Integer Integer Integer 1 and 3 results in 1

Concatenation &, and, + String String String "a" and "b" results in "ab"

Exponentiation **, ^ Integer, Dimensionless real Integer, Dimensionless real Integer, Dimensionless real 2**3. If one of the arguments is real the result is also real. The arguments should be dimensionless. For squaring and cubing dimensioned values, use operations x² and x³. respectively.

Addition + Numeric Numeric Numeric 45.0 + 5. If one of the arguments is real the result is also real. The arguments should have compatible units. The result inherits the units of the arguments.

Subtraction - Numeric Numeric Numeric 45.0 - 5. If one of the arguments is real the result is also real. The arguments should have compatible units. The result inherits the units of the arguments.

Prefix

:

String,
Integer

Integer,
Same as the left

Of the left

String value, integer index. "abcdef":3 results in "abc". The operation extracts the prefix of the left argument of the length specified by the right argument. If the right argument is less than 1 an empty string is the result. If the right argument is greater than the left argument length, the result is the left argument. The following example shows how to extract a string slice: "abcdef".3:2 results in "cd".
String value, string index."abcdef":"cd" results in "ab". The operation extracts the prefix of the left argument before the first appearance of the right argument in the string. When the right argument cannot be found in the string the result is undefined. For example: $2000:" " else "". This will either extract the first field of string register 2000 separated by at least one space, or if 2000 is undefined, empty, contains no space, will result in "".
Integer value, integer index. 16#FF01#:5 yields FF0₁₆. The operation extracts the high order bits of the left argument starting from the bit specified by the right argument. Bits are numbered from 1. x:y is an equivalent to x>>(y-1). The result is the left argument if the right argument is less than 1. The operations : and . can be used together to extract bit fields of an integer value. For example, $1001:6 . 3 extracts bits 6..8 of the value of the integer register 1001. Here 6 is the least significant bit of the field to extract, provided that bits are counted from 1. The length of the field is 3. An equivalent form is $1001.8:6 with both bit numbers specified explicitly.

Observe that 6.3 is a real literal, i.e. the number 6.3. If the . infix operation should follow an integer literal, use space or brackets to separate it.

Suffix

.

String,
Integer

Integer,
Same as the left

Of the left

String value, integer index. "abcdef".3 results in "cdef". The operation extracts the suffix of the left argument starting from the character position specified by the right argument. The first character in a string has the position 1. The result is empty if the right argument is greater than the string length. If the right argument is less than 1 it is assumed to be 1.
String value, string index."abcdef"."cd" results in "ef". The operation extracts the suffix of the left argument after the first appearance of the right argument in the string. When the right argument cannot be found in the string the result is undefined. For example: $2000." " else "". This will either remove the first field of the string register 2000 followed by one space, otherwise, if 2000 is undefined, empty, contains no space, the result is "".
Integer value, integer index. 16#FF01# . 4 yields 1. The operation extracts the low order bits of the left argument. The number of the bits to extract is specified by the right argument. In the example given, four low-order bits are extracted. When the right argument is specifies more bits than an integer value can hold then the result is the left argument. When the right argument is less than 1, the result is 0.

Observe that 6.3 is a real literal, i.e. the number 6.3. If the . infix operation should follow an integer literal, use space or brackets to separate it.

Assignments ->,
#>,
=> Any Register number Of the left "some text" -> 3010. The assignment operation causes execution of a send operation upon the specified register. In the given example the string "some text" is sent to the register 3010. The result of the operation is the sent value. The operation #> functions like ->, but performs the assignment if and only if the value of the left operand differs from the value of the target or the later is not defined. In other words #> has the semantic "send if other". The operation => causes setting the left operand value into the register. Unlike -> it does not send it to the hardware. The register number can be specified as a literal: "some text" -> <System messages>.

Division / Numeric Numeric Numeric 4.0 / 2.1. If one of the arguments is real the result is also real.

Histeresis <§> Integer Real (time) Integer ($2810 > 100 [k/m]) <§> 5 [s]. If the left argument is non zero the result of the operation will remain 1 as long as the right argument specifies. In the given example the condition that the speed represented by the register 2810 is greater than 100 km/h will be true at least 5 s.

Upper damper </> Real Real Real $2810 </> 3 [m/s²]. The operation functions as a filter. The left argument is the signal to be filtered. The right argument is the upper limit of the signal's differential. The operation ensures that the result grows not faster than the limit states. In the given example the limit is 3 [m/s²] for the value taken from the register 2810 (has speed units). The units of the right argument should correspond to the units of the left argument's differential. For instance, if the left argument is measured in A, then the right argument could be A/s.

Lower damper <\> Real Real Real $2810 <\> -3 [m/s²] </> 3 [m/s²]. The operation functions as a filter. The left argument is the signal to be filtered. The right argument is the lower limit of the signal's differential. It ensures that the result falls not faster than the limit states. In the given example the signal's differential is limited by the range -3..+3 [m/s²] using <\> and </> operations. The units of the right argument should correspond to the units of the left argument's differential. For instance, if the left argument is measured in A, then the right argument could be A/s.

Shifts <<,
>> Integer Integer Integer 1 << 3 results in 8.

Else else Any Of the left Of the left $2810 else 0, here the result of the operation is the value of the register 2810 if it is defined. Otherwise it is 0. The operation else functions as follows. If the left argument is defined, the result is the value of the left argument. Otherwise, if the the result is the value of the right argument. If the right argument is also undefined, then the result is undefined too. Using when and else one can build a select operator: $2810 when $1000 else -$2810. Here the result is the value of 2810 if 1000 is non-zero, or the negated value of 2810 otherwise.

Maximum max Numeric Numeric Numeric 2 [km/h] max $2810. If one of the arguments is real the result is also real. The arguments should have compatible units. The result inherits the units of the arguments.

Minimum min Numeric Numeric Numeric 50 [km/h] min $2810. If one of the arguments is real the result is also real. The arguments should have compatible units. The result inherits the units of the arguments.

Bit wise or V, or Integer Integer Integer 1 or 3 results in 3

Sum sum Any Integer Of the left mean ($2810 * d T) sum $4001, here the value of the register 2810 is integrated, but only if the register 4001 is not zero. The right argument of sum is the reset signal. If it is zero the result of sum is also zero or empty string (for sum of strings).

Conditional parameter when Any Integer Of the left $2810 when $1010, here the value of the register 2810 is used only if the value of the register $1010 is not zero. If the right argument of when is zero then the left argument is ignored and the result is treated as undefined. It has the same effect as if the value of the left argument were undefined. If the value of the right argument is not zero the result is the value of the left argument. So the operation when can be used for lazy expression computing. For instance, the expression min ($2810 when $1010) will calculate the minimum of the values of the register 2810, but only when $1010 is not zero. When $1010 is zero the expression is not be calculated, so its value remains unchanged.

Bit wise xor xor Integer Integer Integer 1 xor 3

Synchronization ~ Integer Integer Integer %2810~%2820~%2830. The result of the operation is 1 when both operands reach a non-zero value. It functions as follows. Let both arguments are zero. Then the result is also zero. If one of the arguments becomes non-zero, the operation remembers that fact, but the result remains zero. Only when another argument becomes non-zero, the operation triggers. Its result becomes 1, and a new cycle begins. Together with the register update flag, the operation can be used to eliminate race condition. The expression above will be 1 only when all three registers are updated. The updates may happen asynchronously, i.e. first 2810, then 2830 and 2820 at last. For example, let we want to compose a string from two registers in a way that both have to be updated, we could do it as follows: $100 & $200 when %100~%200.

Infix operations are associated according their priorities. Higher order operation are executed first. Operations of same priority are executed from left to right. For instance 2 + 3 * 4 + 5 is executed as 2 + (3 * 4) + 5 because * has a higher priority than +. The following table shows the priorities of the infix operations:

Priority group Priority Operations

Member extraction 8 . :

Exponentiation 7 ** ^

Multiplicative 6 · % * / << >> rem

Additive 5 + -

Min/max 4 max min </> <\>

Comparisons 3 != /= >< < <= = %= > >= <§> sum

Logic 2 & and or V xor ~

Assignment 1 -> => #> else when

5.11.7. Postfix operations

Postfix operations are applied to one argument. Name of the operation is placed after the arguments. For instance, 5.0². Here ² is the name of the operation that calculates power. The following postfix operations are supported:

Operation	Name(s)	Operand	Result	Example
Quadrate	²	Numeric	Numeric	`$2810²`
Cube	³	Numeric	Numeric	`$2810³`

5.11.8. Brackets

Brackets either represent an operation or used to change the calculation order. The following brackets are supported:

Operation	Brackets	Operand	Result	Example
Absolute value	`\|`...`\|`	Any	According to operand	`\|$2810\|`. The absolute value. For a string it is the string length (integer)
Order change	`(`...`)`	Any	Like the operand	`(2+3)*5`
Truncation	`[`...`]`	Real	Real	`[2.6]` results in 2
Alternative selector	`{`...`}`	list of alternatives	One of the alternatives	`{$200 case >0 then 1; =0 then 0; <0 then -1;}`. Returns sign of the value of register 200

The alternative selector has the following two forms:

if-alternatives-selector
case-alternatives-selector

If-alternatives-selector is similar to an if statement. It has the following syntax:

{ <guard>[|<guard>...] then <alternative>;
...
<guard>[|<guard>...] then <alternative>;
[ others <alternative>; ]
}

Here <guard> is an integer expression, <alternative> are expressions of same type, if real they should have same units. The selector chooses one of the alternatives, which then becomes its result. For this it evaluates the first guard expression. If it is defined and not zero then the result of the first alternative is the result of the selector. If not, the second guard is of the first alternative is evaluated and when defined and non-zero the alterative is selected. The process continues until all guards of the first alternative are evaluated. If none of them fires the alternative, it continues to the second alternative. The process stops when one of the alternatives gets selected. The last alternative can be introduced by the keyword others. Its guard is always non-zero. Each alternative is ended by a semicolon ;, which can be omitted for the last alternative. If none of the alternatives is selected, the result of the selector is an undefined value. As such it can be tested using the else-operation, for instance. Examples:

{$8010>0 then $8010->2100} Send the value of 8010 to 2100, but only if it is positive, otherwise the result is undefined

{ |$8010|>0.001 then (sin $8010)/$8010; others 1 }

A zero-divide-safe way to evaluate	sin x
	x

{ $8010<-10 | $8010>10 then "error"; $8010<-5 | $8010>5 then "warning"; others "OK"; } Results in "error" to 2100 if it is not in the range -10..10, else in "warning" if its out of -5..5, else in "OK". Note that the order of testing the guards is important here, because the choices overlap.

Case-alternatives-selector is similar to a case statement. It has the following syntax:

{ <selector> case
<operator> <choice>[|<operator> <choice>...] then <alternative>;
...
<operator> <choice>[|<operator> <choice>...] then <alternative>;
[ others <alternative>; ]
}

Here <selector> is an expression, <operator> is a binary infix operation resulting in an integer value, <choice> is another expression. Combined together in

<selector> <operator> <choice>

they build an integer guard expression for the alternative it introduces. <alternative> are expressions of same type, if real they should have same units. The selector chooses one of the alternatives, which then becomes its result. For this it evaluates the guard expressions and selects the first alternative with a non-zero guard. The default alternative can be introduced by the keyword others. If none of the alternatives is selected, the result of the selector is an undefined value. Thus a case-alternatives-selector is equivalent to the following if-alternatives-selector

{ <selector> <operator> <choice>[|<selector> <operator> <choice>...] then <alternative>;
...
<selector> <operator> <choice>[|<selector> <operator> <choice>...] then <alternative>;
[ others <alternative>; ]
}

with essential difference that <selector> expression is evaluated only once. Examples:

{ $8010:5.2 case =0 then $8010:1.4->2100; =1 then $8010:1.4->2101; >1 then $8010:1.4->2102; } Extracts the field 5..6 from the value of 8010 and depending on the result sends the field 1..4 to different destinations. Note difference between alternative selector and expressions like <alternative> when<condition>else<alternative> . Latter evaluates both of the alternatives and only then selects one of them. It cannot be used if the alternatives have side effects, like -> used in the example. The alternative selector, evaluates an alternative only when that is selected. Thus only one of the alternatives is evaluated.

{$8010 case !="" then $8010} Provided that 8010 is a string registers, the result is defined only if it contains a non-empty string, which is then the result.

5.11.9. Register policies

An evaluated virtual interface register can be only output. The policy of a register has the following meaning:

On request, the register value is evaluation once. It can be recalculated if its value is requested using LabMapRequest. The register time stamp is set to the time its value is evaluated.
On change, the register value is evaluation each time a register it depends on is changed. Note that if the register value depends on clock it is recalculated permanently. The frequency the register is calculated is limited by the parameter (n ms). For instance, on change, but not oftener that each 100 ms. The register time stamp is calculated along with its value evaluation. It is the nearest to the current moment time stamp of a register it depends on. If the current time is involved into the value evaluation process or the register does not depend on other registers, then the time stamp of the evaluated value is the time now.
Each n ms. The register is evaluation each n ms. The register time stamp is set to the time its value is evaluated.
Triggered. A virtual interface output registers is triggered when in its name the expression in square brackets follows a trigger specification, like in

>Virt>[::]I:I:0:0:-1:-1:Sum 8000->[$1200 + $2810]

Here the trigger specification is 8000->. It consists of the number of the triggering register and the triggering condition:

Condition syntax Condition of the triggered register evaluation Example

<register>-> Each time a value is set to the register <register>. This happens even if the modified state of the triggering register is exactly same as the previous one. Note that when a send operation is initiated on a register, the latter's value is first set and then the register enters an operation-pending state. Upon operation completion the register enters ready state. In this case the virtual register evaluation will be triggered twice. 8000->

<register>=> Same as above, but only if the triggering register enters a settled state. That is: no operation is pending on the register and no error set. In the example of a send operation, the register will be triggered only once upon successful send completion.

If the triggering register has each n ms it will never trigger anything, because it is always either in an error or pending state. Thus it never can have a settled state.

8000=>

Within a triggered expression the value of the triggering register is available via the variable Value. Carefully observe that Value may differ from the actual register value obtained via $<number>. The former is frozen to give an ability to track highly dynamic register updates in a race condition free way. Triggered registers are not evaluated on demand. That is, LabMapRequest would not cause register reevaluation. Also any other policies have no effect. Thus, should the register in the example above be declared on change, then the changes in the registers it depends on will not cause its reevaluation. Each n ms policy when used, only checks that the register gets reevaluated as requested. So the triggering register modification is the only event which may cause reevaluation. The time stamp of a triggered register is one of the triggering event.

When the register depends on other registers it receives a value only if all of them are in a defined state, i.e. have values. Otherwise the register evaluation is postponed. If a register remains undefined for a long time, check if some registers it depends on has an error (timed out) or is undefined.
The time stamp of a virtual on-change register is calculated as maximum of time stamps of the values it depends on.
To have an initialized constant value one should use on change, instead of on request one. The period value is no matter, because the expression will be calculated only once.

5.11.10. Design notes

Designing formulae for calculation of virtual registers requires care and deep understanding of the way the system functions. One can encounter the following problems:

Race condition problem. A race condition exists if the outcome of an operation depends on the order of some operations and this order is not fixed. Let’s consider the following formula: $1200 + $1201. If the register 1200 has the value 1 and the register 1201 has the value –1, the result of the formula is 0. Let’s 1200 changes its value from 1 to 2 while 1201 synchronously changes its value from –1 to –2. The result of the formula should not change. But it could. The outcome depends on the order the system becomes aware of register updates. It may be a sequence 0,1,0 (if 1200 changes first) or 0,-1,0 (if 1201 is the first). Note that there is no general solution for the race condition problem. In each particular case a careful analysis of the system behavior is required. For instance, let’s the differential of the register 1203 is approximated using the formula d$1203 / dt. If the corresponding virtual register is calculated on change, the outcome will be very likely chaotic. The reason for this is that the time involved in dt is changed always, and most likely quicker than the value of the register in d$1203. Therefore sometimes the result of the formula will be zero, just because the value of the register 1203 has not yet been changed and hence d$1203 is zero. A solution here would be changing the policy of the virtual register, so that it would be calculated periodically and not oftener than required to secure that the value of the register 1203 is renewed.
Numeric instability. An operation or algorithm is numerically unstable when small changes of the argument values lead to big changes of the result. It is obvious that numerically unstable formulae will deliver unpredictable results.
Precision loss. A typical example is addition of numbers which exponent parts differ greatly. Such situation may easily appear while calculation of a sum of a big number of items using an accumulator.

Note also that when expression evaluators <int>, <real>, <string> are used, the register should be calculated periodically (each policy). The reason is that the complete list of registers it depends on is unknown. Some of registers may be specified in a string value of an evaluator. Therefore there is no way to react on their changes.

5.12. FLG interface (LabFLG)

The FLG interface is provided by LabFLG.dll. The interface allows to access the variables of an arbitrary number of FLG servers. Any variable of a server can be mapped to a register. For instance:

>FLG>[::]I:S:0:0:-1:-1:First message [Server1.first_message.text]

Here the additional register properties specification is [Server1.first_message.text]. It has the format <server>.<name>. In the given example <server> is Server1 and <name> is first_message.text. The value of <server> indicates the name of the FLG server the variable belongs to. For each server name there should be a string registry key named FLG.<server> containing the IP address or name of the host running the FLG server. In the given example there should be FLG.Server1 registry key. The value of <name> is the name of the FLG variable. It is case insensitive. The FLG variables can be read and written and be of integer, real or string type. The register policy determines the way the FLG variables are accessed. The policies on change and each are allowed. They are implemented using polling the FLG server in background.

The following values of the field <name> have special meaning as described in the following table. It is not obligatory to have any register with <name> field.

Name	Type	I/O direction	Hardware unit	Description
AccelerateTo	Real	Input	km/h	Sending a value informs the FLG server about the current car velocity. It should be periodically sent together with MoveTo or MoveToLatitude / MoveToLogitude to cause the FLG server movement.
AttachmentName	String	Output	-	The name of the currently used FLG road profile attachment. This register can be used to enumerate the attachments. If the current value is empty, then the request operation will give the name of the first attachment (in alphabetical order). A next request will give the name of the next variable. When there is no more attachments it becomes empty. For more information about attachments see FLG.
AttachmentType	String	Output	-	The type of the attachment. When the register AttachmentName is requested and returns a non-empty attachment name, this register is set to the description of that attachment. The description has the format <type> <mapping> [<unit>]. Here type is either `integer`, `contiguous`, `stepped` or `string`. Mapping is either `(s)` or `(t)`. When AttachmentName is requested and set to an empty string, this register is also emptied.
Browse	Integer	Input	-	Sending a non-zero value causes popping up the FLG server's variable browser. To make this handle working the registers VariableName, VariableValue (for both directions has to be declared)
ErrorWindow	Integer	Input	-	The handle to the error messages edit box. If a non-zero value is set the FLG server error messages are written into the edit box window which handle is equal to the sent value.
Exit	Integer	Input	-	Sending a non-zero value to this register ends the FLG server.
Hide	Integer	Input	-	When zero value is sent the FLG server leaves the sleep mode. Otherwise it enters the mode. In the sleep mode the server hides its window and consumes as little system resources as possible.
Host	String	Input	-	The IP address or name of the FLG server. Sending this register causes reconnection to the server. The state of this register reflects the connection state.
Inclination	Real	Output	rad	This register contains the road inclination corresponding to the time moment that last value of the MoveTo register was set. The value of the register is set automatically when a send operation over the MoveTo register is completed. An explicit requesting its value is meaningless.
LoadConfig	String	Input	-	The file name of a FLG server configuration. Sending this register causes loading the configuration from the specified file.
LoadProfile LoadProfile.Spline LoadProfile.Linear	String	Input	-	The file name of a road profile. Sending this register causes loading the road profile from the specified file. The format of the road profile file is described in the FLG documentation. The suffix Spline vs. Linear indicates whether the points of the profile should interpolated using a 3^rd order spline or a linear interpolation. The default is a spline interpolation.
Mode	Integer	Output	-	The current FLG mode. The mode register contains the FLG status and the user defined led bits. For a detailed description refer FLG documentation.
MoveTo	Real	Input	m	Sending a value informs the FLG server about the current car position on the road. It should be periodically sent together with AccelerateTo to cause the FLG server movement. The car position is evaluated relative to the road beginning. Usually it is obtained from an incremental encoder.
MoveToLatitude	Real	Input	rad	Sending a value informs the FLG server about the current car position on the road. It should be periodically sent together with AccelerateTo to cause the FLG server movement. Unlike the MoveTo register, MoveToLatitude sets the position in the form of a GPS latitude-longitude pair. Here GPS stands for Global Postioning System. The corresponding longitude value is taken from the MoveToLongitude register, which should exist and contain the value to the time moment when MoveToLatitude is sent. Upon setting MoveToLatitude causes no I/O with FLG. To use GPS MoveToLatitude, MoveToLongitude registers properly one should always set one of them and then send another ensuring atitude-longitude correctly sent to FLG. For example, an application may first call LabMapSetReal on MoveToLatitude and theh LabMapSendReal on MoveToLongitude.
MoveToLongitude	Real	Input	rad	See MoveToLatitude
MoveToStart	Integer	Input	-	Sending a non-zero value to this register causes the FLG server to jump to the beginning of the currently loaded road profile. Note that the value of the MoveTo register should be set to zero after applying MoveToStart.
Pause	Integer	Input	-	When zero value is sent the FLG server leaves the pause mode. Otherwise it enters the pause mode. In the pause mode the server retains the last position on the road regardless MoveTo register operations.
SetCarHeight	Real	Input	m	Sending a value causes the FLG to change the height of the driver's eye. See SetCarHeight in FLG documentation.
SetSpeed	Real	Output	km/h	This register contains the set speed corresponding to the time moment that last value of the AccelerateTo register was set. The value of the register is set automatically when a send operation over the AccelerateTo register is completed. An explicit requesting its value is meaningless.
Steering	Integer	Input	-	Sending a non-zero value turns the manual steering mode on.
SteerTo	Real	Input	1/m	In the manual steering mode the FLG server should be periodically given the current curvature. The curvature is sent to the server via SteerTo register. The curvature is 1/R, where R is the radius of the curve, the vehicle would drive if the steering wheel is firmly hold in the current position.
StoreConfig	String	Input	-	The file name of the FLG server configuration. Sending this register causes reading the configuration from the server and writing it into the specified file.
TurnGreen	Integer	Input	-	The value of the register is the number of the traffic light to be turned green. Traffic lights are numerated from 1. Zero value turns all lights green.
TurnRed	Integer	Input	-	The value of the register is the number of the traffic light to be turned red. Zero value turns all lights red.
TurnYellow	Integer	Input	-	The value of the register is the number of the traffic light to be turned yellow. Zero value turns all lights yellow.
VariableName	String	Output	-	The name of the currently used FLG variable. This register can be used to enumerate the FLG variables. If the current value is empty, then the request operation will give the name of the first FLG variable (in alphabetical order). A next request will give the name of the next variable.
VariableValue	String	Any	-	This register can be declared as both input and output. Moreover it can be done simultaneously: For an *output* register a request operation retrieves the value of the variable, which name is set in the VariableName register. For an *input* register a send operation causes the variable which name is set in the VariableName register, to be set to the value of the register. If an output VariableValue register exists, it will be set to the actual value of the variable resulted from the set operation. It may differ from one that was set.

5.13. MODBUS/TCP interface (LabModBus)

The MODBUS/TCP (ModBus) interface is provided by LabModBus.dll. The interface allows to communicate with an arbitrary number MODBUS servers using the class 2 protocol (FC1, FC3, FC15, FC16). Any MODBUS register can be mapped to a LabMap register. It is possible to map same MODBUS register to several different LabMap registers. An example of a register declaration:

>ModBus>[::]O:I:-1:100:-1:-1:Analogue input [Coupler1.type=i.addr=0.len=16]

Here the additional register properties specification is [Coupler1.type=i.addr=0.len=16]. It has the format <server>.[<parameter> [<parameters>...]. Parameters can be separated by spaces, colons and points. Each parameter has the format <name>=<value>. In the given example <server> is Coupler1, parameters are type=i, addr=0 and len=1. <server> indicates the name of the MODBUS/TCP server the register should be taken from. For each server name there should be a string registry key named ModBus.<server> containing the IP address or name of the host. In the given example there should be ModBus.Coupler1 registry key. The following table provides the list of parameter names:

Name (case insensitive) Abbreviations Description Default

and a, andmask The value is the 64-bit and-mask applied to the incoming and outgoing data. It is a based unsigned integer. all bits set

address addr The address (counted from 0) of the register. Refer to the documentation of your MODBUS coupler for further information about the register location. It is a based unsigned integer. 0

double

The value, when real and binary is interpreted as a double precision IEEE 754 float. The number of bytes is determined by the length. The representation is big-endian:

Byte 1

Byte 2

Byte 3 ...

Other bytes ...

E₁₁

E₁₀

E₉

E₈

E₇

E₆

E₅

E₄

E₃

E₂

E₁

F₁

F₂

F₃

F₄

F₅

F₆

F₇

F₈

F₉

F₁₀

F₁₁

F₁₂

Here, the bit order shown in the bytes is big-endian (the most significant bit is the leftmost one), the number is S·F·2^E:

S is the sign bit, 0 corresponds to +, 1 does to -;
F_i is the bits of binary mantissa M = 1.F₁F₂F₃... Each following byte adds bits of lesser significance to the mantissa;
E_k determines the exponent part E = E₁₁E₁₀E₉E₈E₇E₆E₅E₄E₃E₂E₁ - 1023.

single

binary

b, bin

This parameter has no value. When specified it has no influence on integer registers. For other types:

Real. With binary specified, the bytes of the value are interpreted as IEEE 754 encoded floating-point number. Otherwise the value is interpreted as an integer number which is then converted to real;
String. With binary specified the first byte of the string corresponds to the first byte of the data. If data is an integer number number then the first byte of the string represents the low-order byte of the number. Without binary parameter the string is converted to an integer number to get the outgoing data, while incoming data are stored into the string in ASCII format.

non-binary

host The host register, for instance [Coupler1.host]. No other parameters may appear. A host register should be input string. Its value is the IP address or name of the ModBus host. It is initialized from ModBus.<server> registry key. Its status reflects the connection state. When sent the value is the IP address or name of the host to connect to. N/A

length l, len The length of the registers (several consecutive registers can be accessed and treated as one value). The length is specified in bits. The byte-oriented data (all types except for bits) should have length 16*n. It is a based unsigned integer. 1 item

or o, ormask The value is the 64-bit or-mask applied to the incoming and outgoing data. It is a based unsigned integer. 0

permutation p, byteorder The value is the byte permutation applied to the incoming and outgoing data. The lowest significant decimal digit of the value corresponds to the first data byte. It indicates which byte of the source data should be taken to produce the first byte of the destination data. This shall be a number in the range 1..8. Zero can be also specified, which means that the destination byte is always zero. The next decimal digit indicates the position of the second byte and so on. Note that the bytes numeration is machine independent. I.e. the values 0..255 correspond to the low order byte no matter which byte order has the given processor. For instance, the value 87654321 denotes a 1-1 permutation, while 12345678 would reverse the byte order. 87654321

shift <<, >> The value is the number of bits to shift the incoming or outgoing data. It is a based unsigned integer in -63..63. For example: shift=5 divides to 2⁵. It is equivalent to >>=5 and <<=-5. 0

signposition sign, signat, signplace The position of the sign bit 1..64. If this option is specified, for the incoming data the result of byte permutation and bit masking is treated as a signed number in the complement format. For the outgoing data, negative numbers are converted to the complement format first with the sign placed into the specified position. For instance, if sign=3, then the bit sequence 101 is treated as -3 = -(not 101 + 1). N/A

single

The value, when real and binary is interpreted as a single precision IEEE 754 float. The number of bytes is determined by the length. The representation is big-endian:

Byte 1

Byte 2

Byte 3 ...

Other bytes ...

E₈

E₇

E₆

E₅

E₄

E₃

E₂

E₁

F₁

F₂

F₃

F₄

F₅

F₆

F₇

F₈

F₉

F₁₀

F₁₁

F₁₂

F₁₃

F₁₄

F₁₅

Here, the bit order shown in the bytes is big-endian (the most significant bit is the leftmost one),, the number is S·F·2^E:

S is the sign bit, 0 corresponds to +, 1 does to -;
F_i is the bits of binary mantissa M = 1.F₁F₂F₃... Each following byte adds bits of lesser significance to the mantissa. A four-bytes value corresponds to single precision 32-bit float. Values of more than four bytes are extended single precision floats;
E_k determines the exponent part E = E₈E₇E₆E₅E₄E₃E₂E₁ - 127.

single

type t, typ The MODBUS register type (see) word

xor x The value is the 64-bit xor-mask applied to the incoming and outgoing data. It is a based unsigned integer. 0

The following types (case insensitive) of the MODBUS registers are supported:

Type	Abbreviations	Read command	Write command	Description
bits	b, bit	FC1, read coils	FC15, force coils	The value of the LabMap register is interpreted as a sequence of bits (up to 64 bits). Depending on the I/O direction the sequence of bits can be either read (output register) or written (input register). The address is the bit address of the first bit in the sequence. The least significant bit of the register value corresponds to the first bit on the hardware side. I.e. the value 10 decimal corresponds to the sequence of bits 1010, where 0 is the first bit of the sequence.
coil	c		FC5, write coil	This type is provided for input integer registers in order to support legacy MODBUS servers incapable of handling the FC15 command. The effect of sending an integer register of this type is that the coil is set on when the register value is not zero. When the value is zero the coil is set off. The parameter length, when specified, must be 1.
integer	i, int, signed	FC3, read multiple registers	FC16, write multiple registers	This is similar to word (see below), but used for signed numbers. The negative values are represented as 2ⁿ + value, where n is the number of bits (binary complement format). The result is read/written as if it were of the type word.
word	w, words	FC3, read multiple registers	FC16, write multiple registers	The value of the LabMap register is interpreted as a sequence of words (two bytes each). Depending on the I/O direction the sequence of words can be read or written. The address is the word address of the first word in the sequence. The most significant bytes of the value go first in the sequence.
real	r, ieee	FC3, read multiple registers	FC16, write multiple registers	This type is used for only real registers. The values are either 4 or 8 bytes IEEE 754 real numbers packed into a sequence of two or four words respectively. For 8 bytes number the low order 32-bits of the mantissa are ignored when read and set to 0s when written. The byte layout is defined by the permutation parameter. The parameters sign position, shift, and-mask, or-mask, xor-mask can also be applied, though not recommended. The pre- and post- data processing are as described below.
permutated	p, permutation	FC3, read multiple registers	FC16, write multiple registers	This type is an equivalent to the type word, but additionally it allows pre- and post-processing of the incoming and outgoing data. The outgoing data are post-processed as follows: The LabMap register value is converted to a 8-bytes unsigned number. If the parameter sign position is specified then signed values are represented using the binary complement format. The permutation is applied to the data bytes The shift is applied to the data The and-mask is applied to the data The or-mask is applied to the data The xor-mask is applied to the data The low order bits (according to the parameter length) of the result is sent to the hardware. The incoming data are pre-processed as follows: The permutation is applied to the data bytes The shift is applied to the data The and-mask is applied to the data The or-mask is applied to the data The xor-mask is applied to the data The data is converted from a 8-bytes unsigned number. If the parameter sign position is specified then the data are treated as a signed number in the binary complement format.

The parameters permutation, and-mask, or-mask, xor-mask, shift and sign position can be specified for only the types permutated and real.

All register policies are allowed. If an output register is requested using on change or each policy, it will be automatically polled in background. One may use integer, real or string register types. The register value is converted as necessary. It is useful to have a ModBus register real, while the corresponding MODBUS register is integer. This allows to integrate the scaling operation into the hardware unit and access the values in their native units. For instance, let an analogue input is used for a temperature sensor (address 10). The analogue input has the value range 0..2¹⁶-1 (0..65535). Let 0 correspond to the temperature -20°C and 65535 to 250°C. The hardware unit of the register should the following form a * K + b. Here K (kelvin) indicates that this is a temperature. The constants a and b can be found from the following set of equations:

-20°C = 253.15K = a*0 + b
250°C = 523.15K = a*65535 + b

So b = 253.15 [K] and a * 65535 + 253.15 = 523.15. This gives a = 280/65535 = 0.00412. Thus the register can be declared as:

>ModBus>[°C:0.00412*K+253.15:°C]O:R:-1:100:-1:-1:Temperature [Coupler1.t=w:addr=10.l=16]

In this case the values read from the two byte analogue input located at the address 10, will be automatically converted to temperature.

Configuration of various MODBUS couplers

All MODBUS couplers presented here work according to the same principle. The I/O modules behind the coupler are accessible over the MODBUS addresses mapped into the coupler's address space. The address values depend on the type of the coupler and is represented in the following table:

Coupler type (vendor)	Digital input table start address	Digital output table start address	Analog input table start address	Analog output table start address
WAGO Fieldbus controller 750-842	0	0	0	0
Phönix contact FL IL 24 BK-PAC Ethernet/Inline bus terminal	0	384₁₀	192₁₀	576₁₀
Beckhoff Buscoupler for Ethernet BK9000	0	2048₁₀	0	2048₁₀

For all types of couplers the make-up of the I/O modules connected to a coupler results in different mapping of the corresponding I/O data into the address space of the coupler. When new modules are added at the end of the modules chain, the address mapping of the previous modules does not change. The data addresses of the added modules will have, depend on the addresses obtained by the previous modules. For information about the necessary address ranges of an I/O module see the appropriated manual from the vendor web site. (Phoenix, WAGO, Beckhoff)

An input variable on the hardware side is represented with an output handle on the LabMap side. An output variable on the hardware side is represented with an input handle on the LabMap^® side.

Coupler type (vendor)	Notes and references
WAGO Fieldbus controller 750-842	For further information (e.g setup) refer Modular I/O System ETHERNET TCP/IP 750-342, 750-842 Manual.
Phönix contact FL IL 24 BK-PAC Ethernet/Inline bus terminal	The coupler has a Web server, which generates the required pages for Web-based management and, depending on the requirements of the user, sends them to the "Factory Manager" or a standard Web-browser. Web-based management can be used to access static information (e.g., technical data, MAC address) or dynamic information (e.g., IP address, status information) or to change the configuration (password-protected). To use LabMap with the FL IL 24 BK-PAC change the configuration as follow: Disable Plug&Play mode (Inline Station - Services) Disable watchdog (Device Configuration - Watchdog) Set "Process Data Watchdog Timeout" to zero (Inline Station - Process Data Monitoring) For further information refer: FL IL 24 BK-PAC Ethernet/Inline Bus Terminal Data Sheet 615503 Hardware and Firmware User Manual for the FL IL 24 BK / FL IL 24 BK-PAC Ethernet/Inline Bus Coupler
Beckhoff Buscoupler for Ethernet BK9000	For further information refer Documentation for the Beckhoff BK9000 Buscoupler for Ethernet

5.14. ExtFix interface (LabExtFix)

This is the interface to the external fixation device (logger) used in Medizinishe Universität zu Lübeck. The interface is implemented by the LabExtFix.dll. An example of a register declaration:

>ExtFix>[::]O:I:0:0:-1:-1:On-line channel 1 [Device.1st on-line channel]

Here the additional register properties specification is [Device.1st on-line channel]. It has the format <server>.<name>. The field <name> indicates the logger's data requested via the register. In the given example it is the first on-line channel (1st on-line channel). The field <server> (Device) indicates the name of the server the register should be taken from. For each server name there should be a string registry key containing the number of the COM port the logger device is connected to. In the given example there should be ExtFix.Device registry key. The serial port used for the communication should have the following settings (Start / Settings / ControlPanel / Ports):

Baud rate: 115200

Data bits: 8

Parity: none

Stop bits: 1

Flow control: none

The following table provides the list of valid names:

Name (case insensitive)	Type	I/O direction	Description
1st on-line channel	Integer, Real	Output	The value of the first on-line channel. When any of four on-line channels is requested the device responses with the new values of all four on-line channels. In other words only one channel (no matter which) should be requested. Note also that the device has the internal polling frequency 6.4 Hz. It means that it has no sense to query for new values more frequently.
2nd on-line channel	Integer, Real	Output	The value of the second on-line channel
3rd on-line channel	Integer, Real	Output	The value of the third on-line channel
4th on-line channel	Integer, Real	Output	The value of the fourth on-line channel
Dump	Integer	Input	This register is used to request off-line data. The value is the number of the off-line channel 1..4 which data has to be requested. When sent the interface reads the values of the channel logged by the device. The progress of the operation is indicated by the Progress register. In the result of the channel dump, its off-line data become ready to request via the corresponding off-line channel register.
Progress	Real	Output	This register is indicates the progress of a off-line channel dump operation. A request to this register gives the current state of the channel dump 0..1, where 1 means ready.
1st off-line channel	Integer, Real, String	Output	The value of the first off-line channel. Before requesting the off-line data one should dump them from the logger using the Dump register. After a request to the register 1st count will returns the number of off-line values currently available for requesting. Each request to the 1st off-line register will extract the most aged off-line value of the 1st channel and diminish the 1st count. Thus an application may read the channel data using the following sequence: Request the Dump register Wait until the Progress reaches the value 1 Request the corresponding off-line register until the value count is not zero Wait for the request completion Get the off-line register value Go to 3. The requested off-line register values can be filtered using the Filter register. The off-line registers will receive when requested only the values with the time stamp greater than one of the Filter register. When the off-line channel register can be a string. In this case the data exchange is made by 64K blocks. Each request to the off-line channel register stores up to 641024/sizeof (int) values. The register time stamp is equal to one of the first value in the buffer. The actual number of the values stored in the register buffer can be obtained as the length of the register divided to sizeof (int*).
2nd off-line channel	Integer, Real, String	Output	The value of the second off-line channel.
3rd off-line channel	Integer, Real, String	Output	The value of the third off-line channel.
4th off-line channel	Integer, Real, String	Output	The value of the fourth off-line channel.
1st count	Integer	Output	The number of values of the first off-line channel ready to request.
2nd count	Integer	Output	The number of values of the second off-line channel ready to request.
3rdcount	Integer	Output	The number of values of the third off-line channel ready to request.
4th count	Integer	Output	The number of values of the fourth off-line channel ready to request.
Command	String	Input	When sent the value of the register is transmitted as-is to the device. The response is placed into the Response register. This feature is provided for debugging purposes.
Filter	any	any	The time stamp of this register is used for filtering the off-line channels.
Response	String	Output	Here the device raw response is placed. See the Command register
Serial number	Integer	Output	When requested the interface stores the device serial number into the register. The register can be requested either directly or using the Dump register. The serial number is also set when the unit number is requested.
Unit number	Integer	Output	When requested the interface stores the device unit number into the register. The register can be requested either directly or using the Dump register. The unit number is also set when the serial number is requested.

5.15. VCI (virtual CAN interface, LabVCI)

The VCI interface is provided by the LabVCI.dll. The interface supports a variety of CAN cards produced by IXXAT. Several cards and multiple CAN ports can be used simultaneously. A VCI register could be defined as:

>VCI>[::]O:I:0:-100:514:295:5 [Board1.ID=5.length=7.p=0123456]

Here the additional register properties specification is [Board1.ID=5.length=7.buffer=5.p=0123456]. It has the format <board>.[<parameter> [<parameters>...]. Parameters can be separated by spaces, colons and points. Each parameter has the format <name>=<value>. In the given example <board> is Board1, the parameters are ID=5, length=7 and p=0123456. <board> indicates the name of a CAN adapter. For each board name there should be a string registry key named VCI.<board> containing a description of the board. In the given example there should be a registry key named VCI.Board1. The description of the board specifies the adaptor type, location, number of CAN ports, their baud rates, operating modes and memory used for buffered I/O. The following table provides the list of the valid VCI register parameter names (case insensitive):

Name

Abbreviations

Description

Default

and

a, andmask

See and-mask

all bits set

binary

b, bin

See binary

non-binary

can

The value is the number of the CAN-bus port used for communication. The adapter card may have several ports numbered starting with 0. Note that each referenced port shall be configured in the board description registry key (VCI.<board>)

The value is the CAN arbitration ID. Different registers may share arbitration ID. It is a based unsigned integer or the wild-card *. When the CAN arbitration ID is specified as *, i.e. id=*, the register works in a special way depending on the I/O direction.

double

See double

single

length

len, l

The length of the data field in bytes. CAN-bus messages may contain up to 8 bytes data. It is a based unsigned integer.

o, ormask

See or-mask

permutation

p, byteorder

87654321

shift

<<, >>

See shift

signposition

sign, signat, signplace, signpos

N/A

single

See single

single

status

stat, state

CAN bus general status as responded by a CAN controller. When specified no other parameters are allowed except than the CAN port parameter. Only output integer registers are allowed. When requested the result is the status of the CAN controller:

Value	Meaning
0	Normal state, on-line
1	Warning, some errors were detected, but the controller is still on-line
2	Error. The controller has switched off-line after multiple errors
3	The controller is off-line

N/A

xor

See xor-mask

The input VCI registers are used for sending CAN data frames. The outgoing data are post-processed as follows:

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0. If a sign position specified then signed numbers are represented in the binary complement format.
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
The permutation is applied to the buffer bytes
The first length bytes of the buffer contents are sent.

The 'upon request' and 'on change' output registers accept unsolicited CAN data frames. For the 'on change' registers the data have an effect on the register value only if they comprise a value different from the actual register value. The 'upon request' registers accept any data. A call to LabMapRequest causes sending a CAN remote frame. The 'upon request' and 'on change' registers can be used when the communicated CAN device sends the data frames either in arbitrary manner or in response to a CAN remote frame. In contrary to this the 'each' registers accept the data periodically. They accept all data frames regardless to their content. One can use such registers the CAN device sends data frames periodically. The incoming data are pre-processed as follows:

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0.
The permutation is applied to the buffer bytes
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
Either the buffer is treated as an unsigned number (for numeric registers) or the first length bytes of the buffer contents are used (for string registers). If a sign position specified then the number is assumed to be in the binary complement format.

Special registers can be specified as ones having the arbitration ID=*. Such registers can be only of string type. They may not have any parameters specified other than the CAN port number or maybe the length of the hardware buffer (if applicable).

There can be only one output register with ID=* per CAN port. This registers accepts all CAN data frames regardless their ID. A data frame is stored in the register in the following format. The first four bytes encode the arbitration ID. The first byte contains the low-order 8 bits of the ID. The second byte contains the next 8 bits, etc. The rest of the string body is the data bytes of the frame.
The number of input registers with ID=* is not limited. They are used to send CAN data frames. The format of the register value is same as described above.

A description of an CAN adapter card supported by the VCI interface has the following syntax:

{<adapter-type>:<adapter-number>|<adapter-key>}:<port-data>[,<port-data>]

Here <adapter-type> is one from the table below:

Adapter type	Bus
iPC-i165/ISA iPC-i320/ISA iPC-i386/ISA	ISA
CANdy CANdy-lite	LPT
iPC-i165/PCI iPC-i320/PCI PC-i04/PCI	PCI
tinCAN byteflightCAN	PCMCIA
USB	USB

The <adapter-number> is a positive number specifying the adapter number. Adapters of same type are enumerated from 1. Note that adapters of different types have independent numeration. If only one adapter of a given type is present, its number is always 1. An alternative way to specify an adapter is to use <adapter-key>, which is a number uniquely identifying it. The numbers are installation dependent.

The list of <port-data> describes the CAN ports of the adapter. An adapter depending on its type may support several CAN ports. To make it available for use by a VCI register, one should specify it in the list. The ports in the list are enumerated from 0. Each element of the list (i.e. <port-data>) has the following the syntax:

<baud>:<mode>:<send>:<receive>[:<max-delay>][:async]

Parameter	Description
<baud>	The baud rate (kBaud). The only allowed values are: 1000, 500, 250, 125, 100, 50, 20, 10. It is a based unsigned integer.
<mode>	The operating mode is either 11 or 29. The number represents the number of arbitration bits used.
<send>	The size of the send buffer in CAN telegrams. It shall be greater than 20. It is a based unsigned integer.
<receive>	The size of the receive buffer in CAN telegrams. It shall be greater than 20. Note that the buffer should be big enough to buffer all incoming telegrams without data loss. It is a based unsigned integer.
<max-delay>	The maximal delay in ms, a received CAN telegram may stay in an internal buffer before it will be processed. Processing is initiated either by filling up the buffer or by expiring the time period specified by this parameter. Use smaller values for better response time and greater values when receiving a large amount of data.
async	Normally the time stamps of the output VCI registers are generated from the time stamps of the corresponding CAN messages. For this the onboard quartz generator is used. The option async, when specified, prohibits use of the onboard generator. The effect of this option is that the registers time stamps are generated from the CPU clock rather than from the onboard generator. Such time stamps might be more reliable but less accurate.

Here is an example of a board description:

tinCAN:1:500:11:100:200

5.16. DMX interface (LabDMX)

The DMX interface is provided by the LabDMX.dll. The interface supports DMX adapters. Only input registers are allowed. A DMX register could be defined as:

>DMX>[::]I:I:0:-100:514:295:5 [Board1.5]

Here the additional register properties specification is [Board1.5]. It has the format <board>.<channel>. Here <channel> is either

A number of the DMX channel associated with the register. The first channel has the number 1. Different adapter types have different limits of the channels. They are summarized in the table below.
The word channel (case insensitive). There can be only one such register per unit. The value of the register is used to identify the channel number for the register value (see below).
The word value (case insensitive). There can be any number of such registers. When the register is sent, the current value of the register channel (see above) identifies the channel number.

In the given example <board> is Board1, the channel number is 5. <board> indicates the name of an DMX adapter. For each board name there should be a string registry key named DMX.<board> containing a description of the board. In the given example there should be a registry key named DMX.Board1. A description of an DMX board has the syntax <type>[:<parameter>[:<parameter>].]. Here <type> is a specification of the hardware. <parameter> provides additional information to the way the hardware should operate.

Type	Second parameter	Third parameter	Description	Example	Channels
USB	The minimal time (ms) period between two send operations. Lesser values improve reaction time but also require more CPU time, because each write operation causes 512 bytes to be sent. The default value is 50[ms].	-	This board type supports the USBDMX1 and USBDMX2 adapters of the firm Soundlight. The dynamic-link library dashard.dll is required as well as the drivers provided by Soundlight. dashard.dll should be placed into the Windows system directory. Note that the adapter can plugged on the fly. The interface will periodically try to detect whether an adapter is present. Note that only one USB adapter at time is supported by dashard.dll.	USB:100	1..512
USBDMX-One	The number of the USBDMX-One adapter. The adapters connected to the host are numbered from 1.	The minimal time (ms) period between two send operations. Lesser values improve reaction time but also require more CPU time, because each write operation causes 512 bytes to be sent. The default value is 50[ms].	This board type supports the USBDMX-One adapters of the firm Soundlight. The dynmaic-link library susbdmx.dll should be available along the search path. Usually it is installed with the device driver.	USBDMX-ONE:1:10	1..512
LPTn	-	-	n is the LPT number 1..4, the adapter attached to. The dynamic-link library lpt_dmx.dll should be placed into the Windows system directory. Note that only one LPT adapter is allowed at time is supported by lpt_dmx.dll.	LPT1	1..48

5.17. IAVCAN (IAV CAN interface, LabIAVCAN)

The IAVCAN interface is provided by the LabIAVCAN.dll. The interface supports the CAN cards produced by IAV. Several cards and multiple CAN ports can be used simultaneously. A IAVCAN register could be defined as:

>IAVCAN>[::]O:I:0:-100:514:295:5 [Board1.ID=5.length=7.p=0123456]

Here the additional register properties specification is [Board1.ID=5.length=7.buffer=5.p=0123456]. It has the format <board>.[<parameter> [<parameters>...]. Parameters can be separated by spaces, colons and points. Each parameter has the format <name>=<value>. In the given example <board> is Board1, the parameters are ID=5, length=7 and p=0123456. <board> indicates the name of a CAN port. An IAV adapter may have several ports each of them is addressed as a separate board. For each board name there should be a string registry key named IAVCAN.<board> containing a description of the board. In the given example there should be a registry key named IAVCAN.Board1. The description of the board specifies the adapter type, location, number of CAN ports, their baud rates, operating modes and memory used for buffered I/O. The following table provides the list of the valid IAVCAN register parameter names (case insensitive):

Name

Abbreviations

Description

Default

and

a, andmask

See and-mask

all bits set

binary

b, bin

See binary

non-binary

double

See double

single

extendedid

extended, extID, extID, ext, e

The value is either 0 or 1. The value zero indicates that the arbitration ID has standard 11-bit size. The value one is used for extended 29-bit arbitration IDs. For an output register this parameter does not influence the register's ability to receive CAN messages with IDs of any length.

length

len, l

The length of the data field in bytes. CAN-bus messages may contain up to 8 bytes data. It is a based unsigned integer.

o, ormask

See or-mask

permutation

p, byteorder

87654321

shift

<<, >>

See shift

signposition

sign, signat, signplace, signpos

N/A

single

See single

status

stat, state

Value	Meaning
0	Normal state, on-line
1	Warning, some errors were detected, but the controller is still on-line
2	Error. The controller has switched off-line after multiple errors
3	The controller is off-line

N/A

The input IAVCAN registers are used for sending CAN data frames. The outgoing data are post-processed as follows:

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0. If a sign position specified then signed numbers are represented in the binary complement format.
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
The permutation is applied to the buffer bytes
The first length bytes of the buffer contents are sent.

The data are stored into 8 byte buffer. The undefined buffer bytes are padded with 0.
The permutation is applied to the buffer bytes
The shift is applied to the buffer bytes
The and-mask is applied to the buffer
The or-mask is applied to the buffer
The xor-mask is applied to the buffer
Either the buffer is treated as an unsigned number (for numeric registers) or the first length bytes of the buffer contents are used (for string registers). If a sign position specified then the number is assumed to be in the binary complement format.

A description of an CAN adapter card supported by the IAVCAN interface has the following syntax:

{<port-name>|<port-position>}:<baud>:<polling-period>[:async]

Parameter	Description
<baud>	The baud rate (kBaud). It is a based unsigned integer.
<port-name>	The adapter-specific name of the port. It might look like 'IAV UCIF 0 - Channel 0'.
<port-position>	A positive number identifying the port. The first available port has the number 1. The numbers are installation dependent.
<polling-period>	The polling period in ms. It is the maximal period of time between two reading of the incoming messages queue. To achieve a better performance one should keep this parameter adequate to the desired reaction time on the incoming CAN telegrams.
async	Normally the time stamps of the output IAVCAN registers are generated from the time stamps of the corresponding CAN messages. For this the onboard quartz generator is used. The option async, when specified, prohibits use of the onboard generator. The effect of this option is that the registers time stamps are generated from the CPU clock rather than from the onboard generator. Such time stamps might be more reliable but less accurate.

Here is an example of a board description:

IAV UCIF 0 - Channel 0:500:10

5.17.1. LabIAVCANGetPortName

int LabIAVCANGetPortName
(
   unsigned     Index,
   const char * Name,
   int         Size);

This function stores the name of the CAN port associated with Index. Index is zero based. To enumerate all available ports one can call LabIAVCANGetPortName increasing Index until ResRRRNotHandled is returned. ResRRRSuspicious is returned when the name returned via the parameter Name is longer than the buffer size indicated by the parameter Size. In which case the returned name is truncated. The names returned by LabIAVCANGetPortName are ones specified as <port-name> in a board description.

5.18. VXL (Vector XL driver library interface, LabXVL)

The VXL interface is provided by the LabVXL.dll. The interface supports the CAN cards produced by Vector Informatik GmbH. Several cards and multiple CAN ports can be used simultaneously. A VXL register could be defined as:

>VXL>[::]O:I:0:-100:514:295:5 [Board1.ID=5.length=7.p=0123456]

Here the additional register properties specification is [Board1.ID=5.length=7.buffer=5.p=0123456]. It has the format <board>.[<parameter> [<parameters>...]. Parameters can be separated by spaces, colons and points. Each parameter has the format <name>=<value>. In the given example <board> is Board1, the parameters are ID=5, length=7 and p=0123456. <board> indicates the name of a CAN port. An Vector adapter may have several ports each of them is addressed as a separate board. For each board name there should be a string registry key named VXL.<board> containing a description of the board. In the given example there should be a registry key named VXL.Board1. The description of the board specifies the adapter type, location, number of CAN ports, their baud rates, operating modes and memory used for buffered I/O. The following table provides the list of the valid VXL register parameter names (case insensitive):

Name

Abbreviations

Description

Default

and

a, andmask

See and-mask

all bits set

binary

b, bin

See binary

non-binary

double

See double

single

extendedid

extended, extID, extID, ext, e

length

len, l

The length of the data field in bytes. CAN-bus messages may contain up to 8 bytes data. It is a based unsigned integer.

o, ormask

See or-mask

permutation

p, byteorder

87654321

shift

<<, >>

See shift

signposition

sign, signat, signplace, signpos