EmCan provides for each port of a device to have up to 6 bytes of function ID, with the meaning of these IDs left to the application above EmCan. Port function IDs are inquired and reported via the PORTFUNC frame.
On the MorBus, the port function IDs are used to provide a means for host applications to recognize ports with known functions regardless of what devices they are within and across devices from different manufacturers. This allows host software to work with new devices without having to have prior knowledge of those devices. Devices can still have ports with arbitrary functions that are not covered by this specification.
In a sense, the port function IDs described here are the machine-interpretable equivalent of the port description strings returned by the PORTDESC response via the virtual byte stream from a node. The port description strings are for display to a user, whereas the port function IDs provide that information to host applications in a standardized way.
The MorBus port function ID bytes are in a hierarchy. The meaning of each byte can only be interpreted within the context of the preceeding bytes. The number of function ID bytes can vary. All are at least one byte long, and can be up to 6 bytes long.
This section describes the meaning of the 1 to 6 port function ID byte string, organized by ascending first byte value. When parameters are shown following the first byte value, these are implied to be single bytes with values interpreted in unsigned integer format unless explicitly described otherwise.
The port function ID strings are:
Reserved.
DCC encoder or power station.
Signaln is the sequential number of the independent DCC signal within the single device that contains the port. DCC signals that can operate independently of each other each must have separate numbers.
For example, if a DCC power station has a main track and a test track output, but only one is driven at a time, then the device has a single DCC signal. If however the main track and test track output can be driven with separate DCC signals at the same time, then each must have a different number.
Numbers within a device start at 0 and go up sequentially.
Confign is the number of the DCC configuration that applies to the port. Confign values of 0-3 are reserved for configurations that drive the main track output, and 4-7 for configurations that drive the test track output.
Configuration 0 is for normal operation of the main track.
Configuration 4 is for the test track in service mode as defined by the NMRA recommended practice 9.2.3. Note that, among other things, the current must be limited to 250 mA in this mode.
Configuration 5 is for the test track in test mode where higher current may be desirable for testing operation of one or a small number of rolling stock on the track, and other restrictions of RP 9.2.3 need not be applied.
Configurations 1-3 are for other main track configurations, and 6 and 7 for other test track configurations.
The special confign value of 255 indicates that this port is not specific to a particular configuration, and applies to the DCC signal as a whole.
Func indicates the function of this port, which applies to the DCC signal identified by signaln and the configuration specified by confign. The defined values of func are:
Configuration select. This port is always readable. If the DCC signal supports multiple configuratons, then this port is also writable. The port must be of type bits, dimension of unscaled numeric, and integer. Confign for this type of port must be 255.
The port value identifies the current configuration on reading, and writing to the port sets the current configuration. Configuration IDs use the same numbers as the confign parameter, described above. On a write to set a configuration not supported by the device, the device may either ignore the request, or switch to some other default configuration, which may depend on the requested one. However, reads must always return the actual current configuration, regardless of what was last written.
In general, a configuration is a collection of settings that will apply to the DCC signal when that configuration is selected. Ports related to a specific configuration do not represent live values, but the value that will be set when the configuration is selected.
The live values are set from the configuration on a valid write to this port, whether that configuration was previously selected or not. The live values are initialized from a configuration whenever a configuration is selected. These live values may be modified afterwards, but are re-set from the configuration even if the existing configuration is selected again. Changing live values does not change the values of the currently selected configuration.
DCC current. This port is readable, not writeable, and has dimension electric current. It reports the measured DCC current. Since this is inherently a live value only, confign must not specify a particular configuration.
DCC maximum current limit. This port is always readable, may be writeable, and has dimension of electric current.
DCC power stations need to somehow prevent accidental short circuits accross the track or excessive load from causing damage. This may be in the form of current limiting (drop voltage as necessary to reduce current), a physical fuse or circuit breaker, a electronic fuse, or some other mechanism.
On a read, the port value is the threshold at which the over-current damage prevention mechanism starts to act. Above this current level, normal operation is not guaranteed. The device may range-limit values written to this port.
This port is for the live value when confign is 255, or the setting within the confign configuration otherwise.
DCC over-current trigger time. This port is always readable, may be writeable, and has dimension of time. It is the time limit a over-current condition may persist before action is taken. For example, if a physical fuse is used, then this is the nominal time from the start of the overcurrent condition until the fuse blows.
If this port is writeable, then the "fuse" trip time can be changed. The device may silently limit written values to be within the supported range.
This port is for the live value when confign is 255, or the setting within the confign configuration otherwise.
DCC voltage setting. This port is always readable, may be writeable, and has dimension of EMF. It is the nominal DCC voltage setting. If writeable, the device may silently limit values to within its supported range. However, in no case may this result in a setting outside the NMRA DCC standard. For example, it must not be possible to cause a setting greater than 22 volts regardless of what is written to the port.
This port is for the live value when confign is 255, or the setting within the confign configuration otherwise.
The port is related to the control of a turnout. The outphi and outplo bytes form a 16 bit unsigned integer, with outphi being the most significant byte and outplo the least significant. This value indicates the number of the output of the device that this port pertains to. This number must be whatever the output is labeled as on the device or numbered as in the user documentation.
Func indicates the function of this port, which applies to the device's output numbered outphi:outplo. The defined values of func are:
The global turnout number. Turnouts are numbered 1-65535 within the overall system. The port must have 16 bits, which must be non-volatile. The device must therefore be in configuration mode to change the global number of the turnout controlled by this output. The special value of 0 indicates that no global turnout number is assigned to this output of the device.
Devices that control turnouts must respond to and produce TURNOUT broadast frames
appropriately for all 1-65535 turnout numbers they have any outputs
configured to.
Example: If port 13 is the non-volatile turnout number controlled
by the device's output numbered 5, then the port function bytes for
port 13 should be 2 0 5 0.
The port is the time duration to apply a control signal to the
turnout to make it change state. This can be thought of as the
"pulse" time. This type of port only applies to turnouts that
are actuated for a specific time, such as solenoid type switch
machines. For a solenoid switch machine, this is the length of
time power is to be applied to a solenoid.
The port must have dimension of time.
The port is the time from first application of a control signal
until the turnout is assumed to have mechanically reached its final
state. When no position feedback is available from a turnout,
this is the time the controller will wait, then assume the turnout is
in its new position. When position feedback is available, this
is the minimum time to assume the turnout is in a intermediate state,
regardless of the position feedback information.
The port must have dimension of time.
The port value is the current state of the turnout. The port
value must be a dimensionless, unscaled, and unsigned 8 bit
integer. Defined values for this integer are:
0: The turnout state is unknown.
1: The turnout is closed.
2: The turnout is thrown.
The port may be readable, writeable, and have a non-volatile
initial value.
On a read, the value must indicate the instantaneous state of the
turnout, not what it might be in the process of being set to for
example.
A write sets the turnout to the specific state. Note that
this may not change the instantaneous state of the port for a while
due to the turnout taking some time to perform the requested
action. A read immediately following a write may therefore not
read the same value as just written.
Writing 0 to the port sets the assumed state of the turnout to
unknown when no state feedback is available. This does not
change the turnout state, just cancels assumptions about that
state. When the actual turnout state can be reliably determined
by other means, writing 0 to this port is ignored.
The non-volatile initial setting of this port sets the startup
state. The system will act just as if a write of the
non-volatile initial value of the port was received immediately after
startup. This includes sending a TURNOUT frame indicating the
state of the turnout if that would be otherwise appropriate.
If the port has no non-volatile initial setting, then it defaults
to 0. This means the turnout is left as is, without being
deliberately controlled to be in any particular state. If
reliable position information is available, then the turnout is still
left as is, but the assumed state is set as measured. A read of
this port would therefore indicate the actual measured state, not
0.
For proprietary use. The remaining 0 to 5 bytes are defined by the manufacturer of the device.