The STROUT and STRIN frames together implement a bi-direction stream of bytes between the host and each node. This section describes the content of the bytes delivered over these streams. CAN frames are only the means of transport for chunks of stream data. How the stream bytes were broken up into separate CAN frames has no meaning to the byte streams.
For both directions, data is transferred in packets that start with a opcode byte, possibly followed by data bytes as defined for that opcode. Packets from the host to the node are referred to as "commands", with packets from the node to the host as "responses", although they may not always be sent in direct response to commands. Commands and responses each have their own separate opcode space.
Individual CAN frames are good for sending small amounts of independent pieces of data quickly. They are less well suited for sending verbose data that would fill multiple CAN frames, or data that must be interpreted within the context of significant state that is set by other means. The byte stream interface to each node provides a way of communicating verbose data, although it will have low bandwidth and high latency relative to dedicated CAN frames.
The byte stream interface is well suited to sending one-time configuration information from the nodes to the host. Such information can contain text strings of arbitrary length, for example.
In the command and response listings below, the name of each command or response is shown, followed by a colon, followed by the opcode value, followed by the description of any data values following the opcode byte.
Unless explicitly stated in the descriptions below, parameters to commands and responses have these characteristics:
Any of the characteristics mentioned above that are not explicitly described otherwise will remain as above, whether other characteristics are described differently or not. For example, if a parameter is described as 16 bits with no other qualification, then it is still implied to be integer, unsigned, and with the high byte transmitted first.
Unless otherwise stated, any data parameter referred to as a "string" is a text string using UTF-8 encoding. Devices don't interpret these strings and consider them merely a sequence of bytes to be stored and reported as requested. Applications should also not attempt to parse these strings to interpret any meaning. The purpose of the strings is only for display to the user.
Since whole bytes are used to hold opcodes, the possible command opcodes are 0 to 255. The first 64 commands (0-63) are reserved for EmCan. Applications can define the remaining 192 commands with opcodes 64-255.
Opcode bytes for unrecognized commands must be ignored.
This command is valid at any time, but must be ignored.
Requests the CMDS response, which indicates which of all the possible 0-255 commands are implemented.
Requests the DEVMAN response, which reports the manufacturer name.
Requests the DEVMOD response, which reports the manufacturer's model name.
Requests the DEVDESC response, which reports the manufacturer's description of the device.
Requests the DEVUSE response, which reports the user-defined description of this node's function within the system.
Requests that a PORTDESC response be sent for a range of ports. These report the manufacturer's description of each port.
Firstport is the 16 bit first port number to send a response for, and nports is the 16 bit number of ports. It is suggested for the node to ignore requests for any ports outside its stated port number range. The node may skip sending a response for any port in this range it does not implement, even if such a port is within its port number limit.
Requests that a PORTUSE response be sent for a range of ports. These report the user-defined description of how each port is used within the system.
Firstport is the 16 bit first port number to send a response for, and nports is the 16 bit number of ports. It is suggested for the node to ignore requests for any ports outside its stated port number range. The node may skip sending a response for any port in this range it does not implement, even if such a port is within its port number limit.
Sets the user-defined device usage string reported by the DEVUSE response. N is the number of bytes in the string, and string is the bytes. There must be exactly n bytes in string.
The maximum possible string length is 255 bytes, since that is the maximum value the n parameter can have. The actual maximum string length stored by a device may be smaller, in some cases significantly smaller. Devices must read the specified number of string bytes, but may truncate the string to some internally defined maximum. If this command is not implemented, then the DEVUSE string is unsettable and is always the empty string.
This command writes a non-volatile setting. Nodes must be in configuration state to accept new non-volatile settings. There are other issues that should be kept in mind when writing non-volatile values. For details see the Non-volatile Settings section of this specification.
Sets the user-defined usage string reported by the PORTUSE response for a particular port. Port is the 16 bit number of the port the PORTUSE string is being set for. N is the number of bytes in the string, and string is the bytes. There must be exactly n bytes in string.
The maximum possible string length is 255 bytes, since that is the maximum value the n parameter can have. The actual maximum string length stored by a device may be smaller, in some cases significantly smaller. Devices must read the specified number of string bytes, but may truncate the string to some internally defined maximum. If this command is not implemented, then none of the PORTUSE strings are settable and are always the empty string.
This command writes a non-volatile setting. Nodes must be in configuration state to accept new non-volatile settings. There are other issues that should be kept in mind when writing non-volatile values. For details see the Non-volatile Settings section of this specification.
Causes the node to provide out of band synchronization information about its response stream. Specifically, this causes a STRIN frame to be sent with 0 data bytes at the next opportunity before a opcode byte. A STRIN with 0 data bytes is passed on to clients of any EmCan server with the STRINSYN response. See the description of the STRINSYN response for details.
Since whole bytes are used to hold opcodes, the possible response opcodes are 0 to 255. The first 64 responses (0-63) are reserved for EmCan. Applications can define the remaining 192 responses with opcodes 64-255.
Opcode bytes for unrecognized responses must be ignored.
This response is valid at any time, but must be ignored.
Provides the explicit list of stream commands implemented by this node. Each bit in the 32 data bytes corresponds to a different command. A 1 bit indicates the command is implemented, and a 0 bit that it is not. The commands are listed in opcode order from the least to most significant bit within each byte, and in the bytes in the order they are sent.
Provides the text string name of the manufacturer of the device. This is for display to a user and is not intended to be interpreted by software.
N is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string.
Provides the text string model name of the device. This is for display to a user and is not intended to be interpreted by software.
N is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string.
Provides the text string description of the device. This is for display to a user and is not intended to be interpreted by software. This string is meant to be a "short" description. For example, it could be displayed in a list of all devices found on the bus to give the user a quick idea what this device is. This string is set by the manufacturer and is not intended to be changed in the field.
N is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string.
Provides the text string description of how this node is used within the system. This is for display to a user and is not intended to be interpreted by software. This is meant to be a "short" description. For example, it could be displayed in a list of all devices found on the bus to give the user a quick idea how each device is used. This string, when implemented at all, will generally be initialized to empty by the manufacturer and set by the user when the device is installed in the system. This string should be saved in non-volatile memory.
N is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string.
Provides the text string description of one port of the node. This is for display to a user and is not intended to be interpreted by software. This is meant to be a "short" description. For example, it could be displayed in a list of all ports of this node to give the user a quick idea what each is. This string is set by the manufacturer and is not intended to be changed in the field.
Port is the 16 bit ID of the port, n is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string. Unimplemented ports must always have a empty description string.
Provides the text string description of how one port of the node is used. This is for display to a user and is not intended to be interpreted by software. This is meant to be a "short" description. For example, it could be displayed in a list of all ports of this node to give the user a quick idea how each port is used. This string, when implemented at all, will generally be initialized to empty by the manufacturer and set by the user when the device is installed in the system. This string should be saved in non-volatile memory.
Port is the 16 bit ID of the port, n is the number of bytes in the text string, and string is the string characters. There are exactly n bytes in string. It is permissible for n to be zero, which indicates the empty string. Unimplemented ports must always have a empty usage string.