The MorBus itself is physically a CAN bus. However, it can be useful to communicate MorBus frames over a bi-directional byte stream. Bi-directional byte streams are more natively available to general purpose computers, and there are various existing ways to transport such streams. Examples of bi-directional byte streams are a RS-232 (COM port on PC systems) connection, a TCP connection, or USB using a single pair of in and out endpoints.
To allow for interoperability, the MorBus byte stream protocol specifies the content of a bi-directional stream of bytes such that all MorBus actions can be caused and seen without actually being directly connected to the MorBus.
The MorBus bi-directional byte stream interface is implemented within the EmCan external stream protocol. Readers of this document are assumed to be familiar with the Emcan external stream protocol.
The EmCan ID response verifies that the stream connection is to a EmCan server, and further gives the name of the EmCan application when the server is specific to a application.
The application specific name of a MorBus server is "MorBus". The name parameter to the ID response is therefore "EmCan:MorBus" followed by a 0 byte. Specifically, the name parameter must be the byte sequence:
69 109 67 97 110 58 77 104 114 66 117 115 0
Command opcodes are one byte in size, so have the range 0 to 255. EmCan reserves the first 64 opcodes (0-63) for its own use, leaving the remaining 192 opcodes (64-255) to be defined by the application. Any command opcodes in the 64-255 range not defined here are reserved for future use. Clients must not send them, and servers must ignore them.
The MorBus-specific commands are:
Turn off and power down to the extent possible, but still retain the ability to respond to the ON command. For example, DCC controllers must turn off track power completely. The exact implementation is device-dependent, but it should be assumed that the overall user intent is to "turn off" the entire layout, but that this level of off is reversible with the ON command.
A ONOFF response will be sent by the bus master after this command is processed.
All devices must disable their outputs or go to their most benign state possible. DCC controllers must send a STOP command, preferably several to guarantee at least one is received by all rolling stock. Devices otherwise keep their EmCan state and continue communicating over the MorBus.
This command is generally sent in response to a user panic action. The user may see something that could cause physical damage if operation continues and feels there is no time to stop individual devices. It should be assumed the user intention is to stop everyhing NOW. It is permissible for some re-initialization to be required before normal operation can resume.
Power up and be ready for normal operation. This is the reverse of the OFF command (above). It should be assumed that the user intent is to "turn on" the layout, which was previously off. Normal power usage is now permissible again.
A ONOFF response will be sent by the bus master after this command is processed.
Requests the ONOFF response, which indicates whether the layout is currently globally on or off.
Requests a measured value from the MorBus controller. Id identifies the requested value in its low 7 bits. The high bit of Id must be 0. See the MVAL response description for a list of the supported id values.
A MVAL response is always sent. This will either indicate the requested value or that the device does not support measuring the value. See the MVAL response description for details.
Perform a function globally on all DCC busses that are set up for normal operation. Func is the function code that indicates what operation is to be performed. Ndat indicates the number of data bytes that follow. Since ndat is a byte, there can be from 0 to 255 data bytes following ndat. MorBus servers that do not recognize a particular function code must ignore the command, but skip over the appropriate number of bytes to stay in sync with the command stream.
Some function codes require a fixed number of data bytes. A DCC command with a invalid number of data bytes for the function code must be ignored. In that case, ndat, not the function code, is used to determine the number of data bytes to skip Put another way, ndat always specifies the actual number of data bytes, regardless of whether that is the appropriate value for the function code.
The DCC commands with each of the defined function codes are:
Sets the speed of a locomotive.
Adr is a 16 bit integer containing the locomotive address. The actual DCC bus address is in the low 15 bits. Bit 15 is 0 if 7 bit addressing is being used, and 1 if 14 bit addressing is being used. Unused bits must be set to 0. In the case of 7 bit addressing, adr has the binary format 000000000aaaaaaa where the address bits are indicated with "a". When 14 bit addressing is used, adr has the format 10aaaaaaaaaaaaaa.
Speed is a 16 bit integer indicating the new desired speed setting. The low 12 bits contain a signed integer value. Values from 1 to 2047 indicate a forward speed and -1 to -2047 a backward speed. The maximum magnitudes of +2047 and -2047 map to the maximum possible speed settings, with the remaining values linearly mapping from stopped to the maximum setting.
Speed of 0 indicates no power is applied to the wheels, but active breaking is not required. This can be considered a "coasting stop".
The actual speed setting sent over the DCC bus is rounded to the nearest attainable value allowed by the DCC protocol. The representation here deliberately has more resolution than can be expressed with the various DCC speed setting commands.
The special value of -2048 causes a hard stop. It should be assumed the user intention is to bring the locomotive to a stop as quickly as possible.
The upper 4 bits of speed are reserved for future use and must be sent as 0 for now. MorBus servers must ignore the command when the upper 4 bits of speed are set to a unrecognized value.
Sets the state of one turnout connected to the DCC bus.
Tout is a 16 bit value containing the number of the turnout to control. This must be a value from 1 to 2040.
This DCC command function assumes a turnout numbering scheme that has not been specified by the NMRA, but is nonetheless in common use in many commercial DCC systems. The NMRA Recommended Practice RP 9.2.1 in section D, Accessory Digital Decoder Packet Format, heading Basic Accessory Decoder Packet Format specifies a 9 bit address space for accessory decoders. A common convention using this DCC packet type has emerged that many turnout controllers adhere to. This command (DCC TURNOUT) implements that convention, and should not be used with equipment that does not adhere to the convention.
The DCC packet referred to above contains a 9 bit decoder address. A 3 bit field selects one of 8 "outputs" of the decoder, and a single bit specifies whether that output is to be turned on or off. Overall, this provides a 12 bit address space for outputs, which can each be individually on or off. The convention embodied in the user interface of many commercial control heads is to use a successive even/odd pair of outputs for each turnout. The turnout is put into its normal state by activating the odd (higher number) output of the pair, and is put into its reverse or alternate state by activating the even (lower number) output of the pair.
The description above implies a address space of 4 turnouts within each of 512 decoder addresses, for a total of 2048 possible turnouts. However, for some reason decoder address 0 is not used in this scheme. Also, the encoder address 511 is reserved for broadcast. This leaves a total of 510 available decoder addresses, each with up to 4 turnouts, for a total of 2040 possible turnouts.
This turnout address space therefore starts with decoder address 1 outputs 0 and 1, and ends with decoder address 510 outputs 6 and 7. Apparently for user interface reasons, the first turnout in this space is numbered 1. This command performs the mapping from this 1-2040 turnout address space to the appropriate basic accessory packet containing a 9 bit address and 3 bit output number.
State is 0 to select the normal position of the turnout and 1 to select the alternate position. 1 causes the even output of the pair to be activated, and 0 causes the odd output to be activated. Other values of state are reserved and must not be sent. MorBus servers must ignore the command when state is set to a unrecognized value.
Sets a turnout to a particular state. Turnout is a 16 bit unsigned integer indicating the number of a turnout. The special value of 0 is reserved and not a valid turnout number. MorBus turnouts are therefore numbered 1 to 65535.
State indicates the state to set the turnout to. The valid values of state are:
0: Unknown. This cancels any assumptions about the actual state of the turnout. This may be used, for example, if it is known the state of a turnout was changed externally outside of MorBus actions, and this can not be detected by the device that controls the turnout. If the state of the turnout can be reliably determined by other means, then this command is ignored.
1: Closed. This command starts the indicated action, but it may take some time for the turnout to reach the new state. If the state of the turnout was previously known but different, then a TOUT response is first sent to indicate the turnout state is unknown when the state switching is started. A TOUT response is sent once the turnout is known to be in its final state, whether it was in that state before the command or not.
2: Thrown. This command starts the indicated action, but it may take some time for the turnout to reach the new state. If the state of the turnout was previously known but different, then a TOUT response is first sent to indicate the turnout state is unknown when the state switching is started. A TOUT response is sent once the turnout is known to be in its final state, whether it was in that state before the command or not.
Response opcodes are one byte in size, so have the range 0 to 255. EmCan reserves the first 64 opcodes (0-63) for its own use, leaving the remaining 192 opcodes (64-255) to be defined by the application. Any response opcodes in the 64-255 range not defined here are reserved for future use. Servers must not send them, and clients must ignore them.
The MorBus-specific responses are:
Reports whether the layout is globablly on or off. On of 0 indicates off, and 1 indicates on. The remaining values of on are reserved.
This response is sent to all clients in response to a OFF, ON, and ONOFF command from any client, or asynchronously whenever the on/off state of the layout is changed for any reason.
Sent in response to a MVAL command. Id identifies the value that was requested and whether or not it is supported. The low 7 bits of id is the id from the MVAL command. The high bit of id is 0 to indicate that a value follows, and 1 to indicate this value is not supported by this MorBus controller and that value is therefore not sent.
Value is 16 bits and is otherwise interpreted dependent on id. Value is not sent when the high bit of id is set.
The values of id and the interpretation of value are:
MorBus power voltage. Value is a 16 bit unsigned integer in units of millivolts.
MorBus power current. Value is a 16 bit unsigned integer in units of milliamps.
Device internal temperature. Value is a signed 16 bit integer in units of 0.1°C. For example, value of 371 indicates 37.1°C.
The various units of value were chosen for communication purposes and do not imply actual accuracy or resolution. The communications units were deliberately chosen to have more accuracy and resolution than real measurements are likely to have or that would be useful. Consult the documentation of a particular MorBus controller to determine the actual accuracy and resolution of the meaured values it reports.
MorBus controllers must respond with the high bit of id set to any ID they do not support or do not recognize.
When the high bit of id is 0, this indicates that a short-circuit or over-current condition has been detected on a power bus, and that this power bus has been shut off in response. This basically says "fuse blown".
When the high bit of id is 1, the power bus has been enabled again. This basically says "fuse reset". This is only sent when the system is capable of resetting the "fuse". The term "fuse" is used here for any mechanism that turns off power as a result of a overcurrent condition. It could be a mechanical single-use fuse, but also a circuit breaker, a electronic circuit that senses current and can shut down power, or something else. Not all systems have resettable fuses, so this response is not guaranteed to be sent.
The low 7 bits of id identify the particular power bus. The defined values are:
MorBus power voltage.
All remaining values are reserved for possible future use.
Indicates the state of a turnout.
Turnout is the 16 bit unsigned integer number of the turnout. Valid values are 1 to 65535.
State is the current state of the turnout. Values can be:
Unknown.
Closed.
Thrown.
Error detected.
All remaining values are reserved for possible future use.