LocoNet mode of the IB RS-232 i/f Uhlenbrock Elektronik GmbH - Version 1.0 (11/2003) ================================================== (corresponding IB software version: 1.500-1.500) This document provides instructions on how to use the "LocoNet mode" of the IB RS-232 interface (added with the IB software release 1.500-1.500). This document does _NOT_ provide instructions regarding the communication protocol used on LocoNet. Please refer to the Digitrax WWW site for that information. *** What is "LocoNet mode" (LN-mode)? LN-mode is a new mode (i.e., a new protocol) of the RS-232 interface of the IB. While the IB up to now was able to understand the P50 and the P50X protocols, starting from IB software 1.500-1.500, the IB can now also understand, on its RS-232 interface, the LocoNet protocol. *** How does it work? The PC can send to the IB LocoNet messages, the IB will check their syntax (and length). If the syntax/length is Ok, the IB will then take care of sending them on LocoNet through the IB LocoNet connectors. Therefore, the PC is freed from the burden of having to comply with the timing requirements of the LocoNet protocol, since these are being taken care of by the IB. On the Rx side, the IB _spontaneously_ sends to the PC _every_ byte that it shall receive through LocoNet. On the Rx side it is therefore the PC which is responsible for "interpreting", from the data bytes sent to the PC by the IB, if and which LocoNet messages have been received from LocoNet. In a sense, this is similar to what happens on the Tx side: the timing information of the Rx bytes is "lost": the IB shall report to the PC each and every byte received from LocoNet, however, the exact timing of this reporting action (when each byte will be sent to the PC) is only loosely related to the timing on LocoNet: there is a "skew" of some variable number of milliseconds (or fractions thereof) between the moment when a byte has been received from LocoNet and the moment when it will be sent to the PC. (With regard to the 'rx side', please read the note at the end of this document). *** IB RS-232 initialization and configuration (with regard to LN-mode). Using PC "LocoNet" software with an IB in LN-mode The BABI (Break and Automatic Baudrate Identification) procedure still works even if the IB is in LN-mode, however, there is one exception: if the IB has been set for 16457 bps and if SO #26 has been set to the value 0, then the 'long break' (part of the BABI procedure) won't reset the baudrate to 2400 bps, this will make the baudrate identification part of the baby procedure fail (it does not work if the IB is still operating @ 16457 bps). Therefore, if the BABI procedure fails, you may wish to try to repeat the 'long break' and then try again to communicate with the IB _directly_ @16457 bps. Please note: after having performed the 'long break' (part of the BABI procedure), the IB defaults to: - mixed P50/P50X protocol (with 'X' as 'leading character); - 2400 bps (if SO #26=1 or else (SO #26=0) the baudrate is not changed); - 2 stop bits. While the LN-mode is active, the PC may decide to communicate with the IB at any speed (bit per second): it is not mandatory to use the 16457 bps communication speed which is the official LocoNet bps. (By the way, the bit length of LocoNet is 60 microseconds, corresponding to a speed of 16667 bps. However, since a PC UART cannot generate exactly that speed, the closest possible value (16457 bps) is used - a value which is within the +/-2% tollerance typical of asynchronous serial communications). The 16457 bps speed has been added to the lists of communication speeds supported by the IB in order to have better compatibility btw an IB in LN-mode and PC software which, not being aware of the IB LN-mode, assumes that it is talking "to" LocoNet using a different device (e.g., a Digitrax MS-100). If the PC program is "LN-mode aware", a convenient communication speed is 19200 bps. Using a communication speed lower than 16457 _may_ result in data loss on the rx side and would slow down the max possible data throughput from the PC to LocoNet (through the IB) - and vice-versa. With regard to "compatibility", we are now documenting SO #5 of the IB: it can be set to the value 1 in order to have the IB communicate on its RS-232 interface using only 1 stop bit. The default value of that SO is 2 (two stop bits). If you plan to use your IB with PC software meant to "talk" on LocoNet (and not IB-aware), you should configure your IB this way: - Syntax = LocoNet - Speed = 16457 bps - SO #5 = 1 (one stop bit) Note: forgetting about the current status of SO #5 (e.g., leaving it at the value 2) is a very likely cause for failures in testing commercial software in LocoNet mode (i.e., software which thinks it is operating an MS-100). Furthermore, when using the "LocoNet mode" it is important to make sure that SO #6 has been disabled or set for a very low value. If this is not so (e.g., if this SO is left at its default value: 254), a Power-Off (OPC_GPOFF) message seen on LocoNet (e.g., sent by the PC) shall cause the CTS line to stay in the "inactive" state for the amount of time specified by that SO (i.e., possibly a rather long time: up to about 13 seconds!). The "temporary value" of this SO can be modified by the PC using the P50Xa "RT" cmd. If the PC program is IB-aware, all of these configuration tasks can be left to the PC program. There is also a special LocoNet message which allows the PC to change the "temporary" value of SO #5 and have the IB communicate on the RS-232 interface using only one stop bit (check below). Finally, it must be noted that even if the IB is being operated by the PC in LN-mode, the PC must still evaluate the status of the CTS line coming from the IB (please refer to the P50X documentation for further details regarding CTS handling in the IB). *** LN-mode activation (and termination) The "LocoNet mode" (LN-mode) can be activated either manually, through the IB menus, or by PC through a new P50Xa command: &LN$55AA This command must be sent with uppercase "L" and uppercase "N". The IB will reply with "]" followed by a . After having sent these two characters, the IB shall automatically send a special LocoNet message: E5 0F 00 49 42 2E 00 00 xx YY YY YY YY YY Cks where: - xx = the flags value (check here below) - YY = non-used data (ignore) LN-mode can be terminated (switching to the mixed P50+P50X mode) by sending one of the Intellibox-specific LocoNet messages mentioned below. Note: the RS-232 configuration is not changed by switching from P50X to LN-mode or vice versa. Specifically, the speed (bps) and the number of stop bits are not affected by a protocol switch. *** LocoNet support in the IB: The IB supports most LocoNet messages pertaining to a LocoNet 'master'. Specifically, it supports (processes) the following LocoNet messages: OPC_IDLE, OPC_GPON, OPC_GPOFF OPC_LOCO_ADR, OPC_SW_ACK, OPC_SW_STATE, OPC_RQ_SL_DATA, OPC_MOVE_SLOTS OPC_LINK_SLOTS, OPC_UNLINK_SLOTS OPC_SLOT_STAT1, OPC_INPUT_REP, OPC_SW_REP, OPC_SW_REQ OPC_LOCO_SND, OPC_LOCO_DIRF, OPC_LOCO_SPD OPC_WR_SL_DATA (length = 14 bytes) OPC_IMM_PACKET (length = 11 bytes) OPC_SL_RD_DATA (length = 14 bytes) In addition to the above, there are other LocoNet messages which are specific to the Intellibox and which are used for communication between the two main CPU's of the IB (SPU and KPU) as well as for other purposes. These messages have header OPC_IMM_PACKET or OPC_PEER_XFER with a length of either 7, 15 or 31 bytes (see below for doc on a group of those messages with length = 15 bytes). The 'fastclock' function is not currently provided by the Intellibox. Programming Track access (decoder read/write) is supported: the 'standard' messages defined by Digitrax as well as extensions specific to the Intellibox. Reading Slot #0 can be used to identify the Intellibox. In fact, it can be used to identify all of our 'LocoNet master' devices: one can tell that it is an Intellibox, a DAISY or a Power 2 in analog mode by looking at the answer of a Slot #0 read request. One would find that ID1 and ID2 have these values: ID1 = 'I', ID2 = 'B'. Furthermore, the value of the Speed byte tells the "level" of the LocoNet driver of the Command Station. The current firmware of the Intellibox (IB), of the DAISY and of the Power2 (in analog mode) report the Speed byte as having value 2 (this basically means: the LocoNet driver supports our FRED - used in the "intelligent, 4 locos" mode). Now, if one needs to find out exactly to which of our Command Stations one is connected to (Intellibox, DAISY, Power2 in analog mode - or Digitrax), then a Slot write of Slot #0 has to be performed (e.g. using the very values one just read from that Slot): - a Power 2 in analog mode does not reply at all - an IB/TC replies with LACK, error = 0Eh (OPC_WR_SL_DATA length) - a DAISY replies with LACK, error = 1 - a Digitrax Chief replies with LACK 'Ok' (7Fh) One can tell a Digitrax CS also by looking at ID1 and ID2 of the Slot #0 read. *** IB-related LocoNet messages: There are a few LocoNet messages which have been defined by us (Uhlenbrock Elektronik GmbH) for use with our devices. The IB uses these messages for various purposes. We document here their general structure as well as the content in case of messages which pertain to the control of LN-mode. The general structure is: Opcode OPC_PEER_XFER (0E5h) - for replies (or 'spontaneous messages') OPC_IMM_PACKET (0EDh) - for messages which expect a reply length 15 bytes (0Fh) 12 message data bytes Checksum format of data bytes: SRC, DSTL, DSTH, ReqId, PXCT1, D1, D2, D3, D4, D5, D6, D7 SRC 0 = master, 1 = KPU, 2 = DAISY, 3 = TB or FRED 4 = IB-Switch, 5 = LocoNet modules 70h..7Eh = reserved DSTL/H destination (addressed) device, 0/0 = broadcast "I"/"B" = Intellibox (SPU: the 'main' CPU of the Intellibox) "I"/"K" = Intellibox (KPU: the 'user interface' CPU of the Intellibox) 0..15/"T" = Twin-Box "I"/"S" = IB-Switch "D"/"Y" = DAISY throttle PXCT1 0, D7.7, D6.7, D5.7, D4.7, D3.7, D2.7, D1.7 ReqId this byte is used in order to tell the type of the message, hence also to tell what D1..D7 do hold. In case of LN-mode related messages, ReqId has the decimal value 46 (2Eh): 46 = used for configuring/terminating PC access to LocoNet through the RS-232 interface of the IB. This msg is sent by a non-SPU device with 0EDh header and SRC=1. The reply to this msg is an OPC_LONG_ACK msg (LACK). The SPU automatically sends this msg with 0E5h header and SRC=0 when the RS-232 LocoNet mode is activated by P50Xa cmd. DSTL/H always hold the value 'I'/'B'. D1 holds the cmd. Currently defined cmds are: 0: ask RS-232 'LocoNet' mode driver version # The version # is reported as LACK code, the 1st sw release featuring LN-mode (SPU vers. 1.500) reports a LACK code of 01h. 1: set value of 'tx flags' D2 the value of the 'tx flags': Bit #0: set (1) if the SPU will also "see" this msg (local echo), reset (0) if the SPU will not "see" this msg: it will "only" be seen by LocoNet devices other than the SPU. Bit #1: set (1) if normal priority (non sensor), reset (0) if high priority (sensor) These two flags default to the 'set' status. Bits #2..7: please do not use (leave them at 0) D3..D7 (not currently used) 2: terminate 'LocoNet mode' of the IB RS-232 interface and start mixed P50+P50X mode D2 must hold the value 'P' (50h) D3..D7 (not currently used) After sending the 'LACK Ok' reply, the IB shall also send + ']' (0Dh, 5Dh) to the RS-232/PC (i.e., the typical 'end of cmd reply' for P50Xa cmd replies. 3: set # of stop bits D2 1 or 2 stop bits D3..D7 (not currently used) N.B.: this is a _temporary_ change to the IB RS-232 configuration. The # of stop bits shall revert to the value specified by SO #5 at the next IB reset or at the next RS-232 configuration change (per menus, i.e. per SO's). The reply is either 'LACK Ok' or 'LACK fail' (except for the 0 and 2 cmds, of course). *** Note on the 'rx side' (data sent to the PC while LN-mode is active): Since timing information cannot be exactly deduced from the data stream sent by the IB to a PC while LN-mode is active, that information cannot be used to tell whether a (rare) case of an "interrupted" LN message has occurred. For example, imagine a LN device sending the 1st n bytes of a valid LN message, then stopping for more than the "CD backoff" time and finally resuming sending the remaining bytes of that message. Well, that message, given the too-long pause in-between, cannot be considered a valid LN message. Indeed, the IB, internally, would discard it. However, a PC - assuming there is not an abnormally long pause in-between that message - cannot be positively sure whether that msg was or was not a 'valid' LN message. This is a small 'price' to pay in order to gain the advantage of being able to see other kinds of low level LN events (such as message collisions, etc.). In a future software release, we may consider letting the user select what he prefers: - that things are handled the way they are right now (everything is sent w/o any filtering); - that the IB only sends to the PC valid LN messages.