The EmCan external stream protocol is a way of receiving EmCan information and causing EmCan actions communicated over a bi-directional stream of bytes. This is advantageous since the native EmCan is physically a CAN bus, which most general purpose computers do not have a direct interface to. Furthermore, since there are already standard ways of transporting a bi-directional stream of bytes over various media and distances, the stream interface allows for remote monitoring and control of a EmCan bus.
Examples of bi-directional byte stream interfaces directly available to most general purpose computers are:
The EmCan external stream protocol requires two separate byte streams, one in each direction. Some transports inherently provide a byte stream in both directions (like TCP), while others only in one direction. Somehow, two byte streams must be established with both together being interpreted as a bi-directional byte stream. Details specific to particular transport means are in the section Transport-specific Requirements section later on this page. This section here describes the data carried on the bi-directional byte stream, regardless of how it is implemented.
Communication is between a stream-to-EmCan bridge device and some other computing device. Since this other device is generally intended to control the EmCan bus on behalf of a user, it is referred to as the "client" in this specification, and the EmCan interface device the "server".
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 client to the server are referred to as "commands", with packets from the server to the client as "responses", although they may not always be sent in direct response to commands. Commands and responses each have their own separate opcode space.
Unless explicitly stated in the descriptions below, data values 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.
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.
Commands are the packets of bytes sent from the client (usually a computer intended to control the bus) to the server (the device interfacing to the EmCan bus and presenting this stream protocol to the outside).
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.
The individual commands are:
This command is guaranteed to always be ignored. It is up to the server implementation whether a NOP command resets the client inactivity timeout. To reliably indicate activity with minimum overhead and no state changes, use the KEEPALIVE command.
Causes a PONG response to be sent. This can be useful to verify the bi-directional communication channel.
Requests the ID response. The purpose of the ID response is to verify that the connection is indeed to a EmCan server.
Causes the FWINFO responses to be sent, which report the firmware versions and other information of the device implementing the EmCan stream server.
Requests the CMDS response, which indicates the set of commands implemented by the server.
Reset the EmCan bus. This will invalidate all existing address assignments. A RESET response will be sent after the reset has been performed. Each node on the bus will then request a new address assignment, which will cause a ADR response to be sent as each node is assigned its address.
Sends a standard CAN data frame on the EmCan bus. Id16 contains the 11 bit ID in a 16 bit integer. Ndat is the number of data bytes that will be included in the CAN frame, and must be 0 to 8. Exactly ndat data bytes follow the id16 parameter.
Sends a extended CAN data frame on the EmCan bus. Id32 contains the 29 bit ID in a 32 bit integer. Ndat is the number of data bytes that will be included in the CAN frame, and must be 0 to 8. Exactly ndat data bytes follow the id32 parameter.
Sends a standard remote request CAN frame on the EmCan bus. Id16 contains the 11 bit ID in a 16 bit integer.
Sends a extended remote request CAN frame on the EmCan bus. Id32 contains the 29 bit ID in a 32 bit integer.
Requests enumeration of the EmCan devices. A ADR response will be sent for all currently known nodes with assigned addresses.
This indicates to the server that the client is still present and connected. Servers may implement a client inactivity timeout such that they "close" the connection or otherwise deallocate resources associated with the specific client when no activity is detected for the duration of the timeout.
Receiving any valid command or data byte except for a NOP command must reset the timeout. It is up to the server implementation whether NOP commands reset the timeout or not. The KEEPALIVE command is a means for the client to cause activity while otherwise using the minimum resources to do so.
Servers are not required to implement a timeout and close a connection after some period of inactivity. This can depend on the nature of the connection, the resources required in the server to maintain it open, etc. For example, if the stream is over a dedicated RS-232 connection, there is nothing to close and little point in knowing whether a client is active on the other end or not. However, a small TCP server could implement a limited number of simultaneous TCP connections, so a client that was disconnected without the TCP connection being deliberately closed could cause one of the limited number of connections to be unusable. In this case, unilaterally closing the TCP connection after a period of client inactivity is probably a prudent protection scheme.
If a timeout is implemented, it must not be less than one minute (60 seconds). A client that regularly sends a KEEPALIVE command (or any other valid command) at a interval of less than one minute is guaranteed to be safe from being closed by the server due to inactivity. Since the minimum timeout is one minute at the server, transport and other delays should be considered when deciding how often a client should force activity. For example, a TCP client might send a KEEPALIVE every 55 seconds if it is determined that network delays and delays in the client will not exceed 5 seconds.
N is the number of bytes to send over the stream. These bytes follow n. There must be exactly n dat bytes.
All the data bytes of one STROUT command are guaranteed to be sent together (when they are sent at all), regardless of whether other processes are trying to send bytes concurrently. In general, one STROUT command should be used to send a single command over the stream interface. Sending more than one is possible, but the larger number of bytes that must be sent at one time increases the chance that they can't be sent at all.
A STROUT response will be sent indicating the result of this attempt to send bytes to the bus node.
This command can be sent with 0 data bytes to get the stream status as reported by the STROUT response.
The last 8 command opcodes of the EmCan range (56 - 63) are reserved for use private to the particular device implementation. These commands MUST NOT be used to provide any additional features relative to EmCan during end user or other normal operation. Their purpose is to allow manufacturers to implement special features for production test, diagnostics, debugging, and the like.
A client should only send one of these commands when it has determined the particular EmCan server is of a type it has special knowledge of. The FWINFO response should provide the necessary information to determine this. The format of the DEBUG commands are otherwise not specified since proprietary knowledge between the server and client is required for their use anyway.
Servers must ignore all opcode bytes they do not implement. However, that does not allow for clients to send DEBUG commands without specific knowledge. A server that does not implement a particular DEBUG command will interpret any data bytes to it as a regular command stream, which could have unpredictable and undesirable consequences.
Servers must show which DEBUG commands they implement, if any, in the CMDS response just like for all other commands. It is a violation of the EmCan specification to "hide" a debug command by not indicating it is implemented in the CMDS response, but then responding to it by other than discarding the opcode byte and interpreting the first data byte as the opcode of the next command.
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 is a valid response, but otherwise has no meaning. The client must tolerate receiving a NOP at any time a response opcode byte is expected.
Sent in response to the PING command only.
Identifies the server. This is intended to verify to a client that it is indeed communicating with a EmCan server. This could be useful, for example, in looking for a EmCan stream TCP server over a limited number of possible IP addresses, like a local class C network. The chances of something other than a EmCan stream server sending exactly the required ID response are exceedingly slim.
Name is a string of ASCII printable characters followed by a single 0 byte. Only the printable ASCII characters 32 thru 126 are allowed. The name string must start with "EmCan". If the server implements a particular application above EmCan, then this must be followed by the colon character (":") and then the name of the application. Application names are specified together with the unique Application ID. If the server implements only EmCan, then the name string must be just "EmCan" with no colon.
Version is the major version number of this specification the server was implemented to. It must be at least 1.
When the stream connection is of a type so that the server knows when a new connection to a client is established, then this response is sent immediately after the connection is established. For example, a TCP connection must be deliberately opened and closed, which the server can be aware of. For a TCP connection, this response is therefore required to be sent immediately after the connection is made. With other connection means, like RS-232 for example, the server does not know if a client is listening and therefore when the client considers the connection to have "started". In that case, this response is only sent when a ID command is received by the server. In all cases, this response will be sent when a ID command is received, whether it was also sent when the connection was originally started or not.
Provides the firmware or other implementation version numbers of entities in the chain from the server to the actual EmCan. Generally this would be a device with a physical EmCan connection on one side and the physical stream connection on the other. Such devices are expected to be implemented with one or more microcontrollers, which then each would have its own firmware version. This does not, however, preclude devices with a all-hardware implementation, or even "devices" that are purely a program or a software layer on a general purpose computer. The name "firmware" is used to refer to all of these since that is the most likely realization, but that is merely a arbitrary name for the purpose of describing this response.
Vblockid is the 24-bit EmCan vendor block and device ID within that vendor block of the device (whether physical or not) implementing a function in the chain from the stream to the actual EmCan. The combined 24-bit vendor block and device ID is described in detail for the VBLOCKID parameter to the ADRASSIGN frame.
Type, majver, minver, and sequence are each 16 bit parameters. Briefly, these are the firmware type, major version number, minor version number, and build sequence number, and are the same as the parameters to the FWINFO frame.
Indicates which commands this server implements. The 32 dat bytes provide one bit for each of the possible 0-255 command opcodes. The 0-255 opcodes in order correspond to the bytes in the order they are sent, and from the least to most significant bit within each byte. For example, bit 0 (the LSB) of dat0 corresponds to opcode 0, bit 1 to opcode 1, bit 0 of dat1 to opcode 8, etc. A 1 bit value indicates that the command is implemented, and a 0 that it is not. The client should not send a command indicated as unimplemented by this response, even if it is required according to this specification.
This response is only sent in response to the CMDS command.
This mechanism allows for optionally implemented commands, and a easy mechanism for clients to adapt to servers implemented to different versions of this specification. Newer versions may include additional commands. By using the CMDS response, clients do not have to have knowledge of which versions of the specification required which commands. Command are only optional when explicitly defined as such in the Commands section of this specification, above.
Indicates one received CAN frame. This response is sent asynchronously when a CAN frame is received.
Flags is a byte containing several fields:
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
| reserved | RTR | EXT | NDAT | ||||
Reserved bits should be ignored by clients and sent as 0 by servers. They may be defined in future versions of this spec.
RTR is set to indicate the frame is a remote request as apposed to a data frame. The number of data bytes in a remote request is always 0.
EXT is set to indicate a extended as apposed to standard frame. Standard frames contain 11 bit frame IDs, and extended frames 29 bit IDs. The id parameter to this response is 16 bits for standard frames and 32 bits for extended frames.
NDAT is the number of data bytes. This may be 0-8 for data frames and is 0 for remote request frames.
Id is the frame identifier. Standard frames (EXT = 0) use a 11 bit ID and extended frames (EXT = 1) a 29 bit ID. Id is two bytes for standard frames and 4 bytes for extended frames. The EXT bit in the flags byte must be checked to determine the number of id bytes. In both cases the ID is right justified into the 16 or 32 bit id word with the high bits zero.
The dat bytes are the CAN frame data bytes. There are always exactly NDAT dat bytes, except that there are never more than 8 even if NDAT is erroneously set to a larger value.
Reports that the EmCan bus has been reset. Among other things, this invalidates all existing node address assignments. UNADR responses for each existing address assignment will not be individually sent.
Indicates the address assignment of one device on the bus. Adr is the 1-127 EmCan address assigned to the node being reported.
Id6 thru id0 is the globally unique 7-byte ID of the bus node. This is the same 7-byte ID used in the ADRASSIGN frame. Specifically, id6:id5:id4 is the VBLOCKID parameter to the ADRASSIGN frame, and id3:id2:id1:id0 the SERIAL parameter.
This response is sent automatically when a new bus node is assigned its address, but can also be sent at other times to indicate the current address assignment. This response is not sent due to a node being re-assigned its same existing address.
Indicates that a existing bus node address assignment has become invalid. Adr is the 1-127 address that is now unassigned.
This response is sent asynchronously whenever a existing address assignment becomes invalid.
Sent in response to a STROUT command to indicate the status of the stream interface and whether the bytes were successfully sent or not.
Adr is the 1-127 bus address of the node being reported on.
Stat is a single byte that contains several fields:
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
| reserved | OPEN | DEF | NODE | ||||
Reserved bits should be ignored by clients and sent as 0 by servers. They may be defined in future versions of this spec.
OPEN is set only when the stream is definatively open. This is a necessary condition to be able to send bytes over the stream interface. Attempts to send bytes when OPEN is set may still fail if the bus master can not queue the bytes to be sent. This is probably the result of too many bytes attempting to be sent too fast. Note that other processes, such as other clients to the same EmCan server, may be sending bytes over the stream to the same node. This can result in failure to other processes, even if these processes are sending small amounts of data infrequently.
DEF is set after the stream connection status to the remote node is known definatively. This is the case either when the stream is successfully opened or the node actively refused to open it. When DEF is not set, then the stream is not open but could be open in the future. Most bus master implementations will attempt to open the stream periodically until its status is definative. When DEF is set but OPEN not set, then the device does not support the output byte stream to it. Bus masters generally will not retry opening the stream once the node specifically refuses it. The stream will therefore be unavailable at least for the duration of that bus session.
NODE indicates that the addressed node exists.
N is the number of bytes that were sent with the STROUT command this is in response to. To avoid confusion and overruns, the client should wait for the STROUT response from any previous STROUT command before sending a new STROUT command.
Indicates that the next byte of the byte stream from the bus node with address adr will be a opcode.
This response is sent asynchronously whenever the byte stream is started or re-started by the node. Usually this would only be done once shortly after its address was assigned, but this could happen for various reasons, like power temporarily removed from the device, device reset by the user, etc.
This response is also sent as a result of a deliberate SYNC command sent over the virtual byte stream to a node. Note that this is a different byte stream than that to the EmCan server, as described on this page. Bytes are sent over the virtual byte stream to a node with the STROUT command, described above.
Any readers of the virtual stream from a node need to be aware of the break in the protocol. After a STRINSYN, the first data byte of the next STRIN response (below) for that node is always a opcode. Any packet that may have been in progress when STRINSYN is received must be aborted.
When a client first connects to a EmCan server, it has no way of knowing what are opcode bytes and what are data bytes in the stream received from each node (see the STRIN response below). Since such streams can not be correctly interpreted without knowing which bytes are opcodes, clients must discard any received stream data until synchronization is achieved. This means a STRINSYN response must be received for a node before attempting to interpret the stream data from that node.
As mentioned above, STRINSYN responses are sent asynchronously when certain events occur. However, these may not occur for indefinite periods of time. To deliberately cause a STRINSYN response to be sent at the next opportunity when it is known the next byte will be a opcode, the SYNC command must be sent to that node over its byte stream.
In general, a new EmCan client sends SYNC stream commands to all nodes it knows and cares about as part of its initialization procedure. If any STRIN data is received from a node before the STRINSYN for that node, the STRIN data is discarded.
All EmCan clients will receive STRINSYN responses for a node when a SYNC command is sent from any client to that node. Since STRINSYN responses can also be sent asynchronously, clients are encouraged to watch for STRINSYN responses and not send SYNC commands if they are already in sync with the received byte stream from that node.
Indicates data bytes sent by the bus node with address adr over its byte stream.
N is the number of data bytes. Exactly n data bytes must follow n.
Generally, EmCan stream servers will send all stream data from all nodes to all clients. Nodes may send some stream data asychronously, and it may be difficult or impossible for a EmCan stream server to determine which client, if any, caused a particular sequence of bytes to be sent by a node. When a client sends a command over the stream interface to a node, it will receive the response. However, it will also likely see responses to commands from all other clients without seeing the commands that caused them. Clients need to take this into account when processing the stream from each node. Clients are encouraged to watch the stream from each node and not request information that the node has already sent, regardless of why the data was sent.
The last 8 response opcodes in the EmCan range (56 - 63) are reserved for use private to the particular device implementation. These responses MUST NOT be used to provide any additional features relative to the EmCan bus during end user or other normal operation. Their purpose is to allow manufacturers to implement special features for production test, diagnostics, debugging, and the like.
To allow any client to skip over any of these responses without requiring proprietary information, each response follows a specific format. The opcode byte is followed by the nbytes byte, which indicates the number of dat bytes that follow. There may therefore be from 0 to 255 bytes following nbytes. Since the response always includes the opcode byte and the nbytes byte, each response is a total of nbytes+2 bytes long.
The section above defines the meaning of the bytes in the bi-directional stream of bytes between a server and a client. However, various underlying transport means have additional parameters beyond the content of the byte stream. This section defines some of these additional parameters for a few select transport types.
The specific transport types with their unique parameters are:
The device that is connected directly to the EmCan bus and provides the stream interface externally will be the TCP server, and the device that controls or monitors the EmCan bus via this stream (typically a general purpose computer running a user application) will be the TCP client. This is consistent with the use of the names "client" and "server" in the byte stream description, above.
The TCP server will be presented at port 2005 on the server node.
The ID response will be sent by the server immediately after the TCP connection is established. This will be sent before any asynchronous responses due to bus activity or synchronous responses due to commands from the host.
Endpoints 1 IN and OUT will be used to implement the two halves of the bi-directional stream of bytes. These will use the bulk transport mode.
The server (as defined in the Byte Stream section) will be the end device and the client will be the USB host device.