jmri
Class NmraPacket

java.lang.Object
  jmri.NmraPacket

public class NmraPacket
extends Object

Utilities for coding/decoding NMRA S&RP DCC packets.

Packets are (now) represented by an array of bytes. Preamble/postamble not included. Note that this is a data representation, _not_ a representation of the waveform! But this is a class, which might eventually also form a representation object.

This is meant to be a general Java NMRA implementation, so does NOT use JMRI utilities. In particular, it returns null instead of throwing JmriException for invalid requests. Callers need to check upstream.

The function is provided by static member functions; objects of this class should not be created.

Note that these functions are structured by packet type, not by what want to do. E.g. there are functions to create specific packet formats instead of a general "loco speed packet" routine which figures out which type of packet to use. Those decisions are to be made somewhere else.

Range and value checking is intended to be aggressive; if we can check, we should. Problems are reported as warnings.

The basic function is to build a packet with proper addressing, etc:

• oneBytePacket
• twoBytePacket
• threeBytePacket
• fourBytePacket

On top of those are built various special-purpose packet formats. This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Author:

Bob Jacobsen Copyright (C) 2001, 2003

Field Summary

static int	ACCESSORY_SHORT_ADDRESS
static int	LOCO_LONG_ADDRESS
static int	LOCO_SHORT_ADDRESS
static int	NO_ADDRESS

Method Summary

static byte[]	accDecoderPkt(int number, boolean closed) Provide an accessory control packet via a simplified interface
static byte[]	accDecoderPkt(int addr, int active, int outputChannel)
static byte[]	accDecoderPktOpsMode(int number, int cvNum, int data) Provide an operation mode accessory control packet via a simplified interface
static byte[]	accDecoderPktOpsMode(int addr, int active, int outputChannel, int cvNum, int data) From the NMRA RP: Basic Accessory Decoder Packet address for operations mode programming 10AAAAAA 0 1AAACDDD 0 1110CCVV 0 VVVVVVVV 0 DDDDDDDD Where DDD is used to indicate the output whose CVs are being modified and C=1.
static byte[]	accDecoderPktOpsModeLegacy(int number, int cvNum, int data) Provide a legacy operation mode accessory control packet via a simplified interface
static byte[]	accDecPktOpsModeLegacy(int addr, int cvNum, int data) From the NMRA RP: The format for Accessory Decoder Configuration Variable Access Instructions is: {preamble} 0 10AAAAAA 0 0AAA11VV 0 VVVVVVVV 0 DDDDDDDD 0 EEEEEEEE 1 Where: A = Decoder address bits V = Desired CV address - (CV 513 = 10 00000000) D = Data for CV This is the old "legacy" format, newer decoders use the "Basic Accessory Decoder Packet"
static byte[]	accSignalDecoderPkt(int outputAddr, int aspect) From the RP: Extended Accessory Decoder Control Packet Format The Extended Accessory Decoder Control Packet is included for the purpose of transmitting aspect control to signal decoders or data bytes to more complex accessory decoders.
static byte[]	analogControl(int address, boolean longAddr, int function, int value) Provide an NMRA analog control instruction Note that the NMRA draft of Fall 2004 only defines the value of "1" for the "function parameter", calling that the value for "volume control".
static byte[]	consistControl(int address, boolean longAddr, int consist, boolean directionNormal) Provide an NMRA consist control instruction
static String	format(byte[] p) Convert NMRA packet to a readable form
static byte[]	fourBytePacket(int address, boolean longAddr, byte arg1, byte arg2, byte arg3, byte arg4) Create a packet containing a four-byte instruction.
static byte[]	function0Through4Packet(int address, boolean longAddr, boolean f0, boolean f1, boolean f2, boolean f3, boolean f4)
static byte[]	function13Through20Packet(int address, boolean longAddr, boolean f13, boolean f14, boolean f15, boolean f16, boolean f17, boolean f18, boolean f19, boolean f20)
static byte[]	function21Through28Packet(int address, boolean longAddr, boolean f21, boolean f22, boolean f23, boolean f24, boolean f25, boolean f26, boolean f27, boolean f28)
static byte[]	function5Through8Packet(int address, boolean longAddr, boolean f5, boolean f6, boolean f7, boolean f8)
static byte[]	function9Through12Packet(int address, boolean longAddr, boolean f9, boolean f10, boolean f11, boolean f12)
static byte[]	oneBytePacket(int address, boolean longAddr, byte arg1) Create a packet containing a one-byte instruction.
static byte[]	opsCvWriteByte(int address, boolean longAddr, int cvNum, int data)
static byte[]	speedStep128Packet(int address, boolean longAddr, int speed, boolean fwd)
static byte[]	speedStep14Packet(int address, boolean longAddr, int speed, boolean fwd, boolean F0)
static byte[]	speedStep28Packet(int address, boolean longAddr, int speed, boolean fwd) From NMRA RP 9.2.1 A speed and direction instruction is used send information to motors connected to Multi Function Digital Decoders.
static byte[]	threeBytePacket(int address, boolean longAddr, byte arg1, byte arg2, byte arg3) Create a packet containing a three-byte instruction.
static byte[]	twoBytePacket(int address, boolean longAddr, byte arg1, byte arg2) Create a packet containing a two-byte instruction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_ADDRESS

public static final int NO_ADDRESS

See Also:

Constant Field Values

LOCO_SHORT_ADDRESS

public static final int LOCO_SHORT_ADDRESS

See Also:

Constant Field Values

LOCO_LONG_ADDRESS

public static final int LOCO_LONG_ADDRESS

See Also:

Constant Field Values

ACCESSORY_SHORT_ADDRESS

public static final int ACCESSORY_SHORT_ADDRESS

See Also:

Constant Field Values

Method Detail

oneBytePacket

public static byte[] oneBytePacket(int address,
                                   boolean longAddr,
                                   byte arg1)

Create a packet containing a one-byte instruction.

twoBytePacket

public static byte[] twoBytePacket(int address,
                                   boolean longAddr,
                                   byte arg1,
                                   byte arg2)

Create a packet containing a two-byte instruction.

threeBytePacket

public static byte[] threeBytePacket(int address,
                                     boolean longAddr,
                                     byte arg1,
                                     byte arg2,
                                     byte arg3)

Create a packet containing a three-byte instruction.

fourBytePacket

public static byte[] fourBytePacket(int address,
                                    boolean longAddr,
                                    byte arg1,
                                    byte arg2,
                                    byte arg3,
                                    byte arg4)

Create a packet containing a four-byte instruction.

accDecoderPkt

public static byte[] accDecoderPkt(int addr,
                                   int active,
                                   int outputChannel)

accDecoderPktOpsMode

public static byte[] accDecoderPktOpsMode(int addr,
                                          int active,
                                          int outputChannel,
                                          int cvNum,
                                          int data)

From the NMRA RP: Basic Accessory Decoder Packet address for operations mode programming 10AAAAAA 0 1AAACDDD 0 1110CCVV 0 VVVVVVVV 0 DDDDDDDD Where DDD is used to indicate the output whose CVs are being modified and C=1. If CDDD= 0000 then the CVs refer to the entire decoder. The resulting packet would be {preamble} 10AAAAAA 0 1AAACDDD 0 (1110CCVV 0 VVVVVVVV 0 DDDDDDDD) 0 EEEEEEEE 1 Accessory Decoder Address (Configuration Variable Access Instruction) Error Byte

accDecPktOpsModeLegacy

public static byte[] accDecPktOpsModeLegacy(int addr,
                                            int cvNum,
                                            int data)

From the NMRA RP: The format for Accessory Decoder Configuration Variable Access Instructions is: {preamble} 0 10AAAAAA 0 0AAA11VV 0 VVVVVVVV 0 DDDDDDDD 0 EEEEEEEE 1 Where: A = Decoder address bits V = Desired CV address - (CV 513 = 10 00000000) D = Data for CV This is the old "legacy" format, newer decoders use the "Basic Accessory Decoder Packet"

accSignalDecoderPkt

public static byte[] accSignalDecoderPkt(int outputAddr,
                                         int aspect)

From the RP: Extended Accessory Decoder Control Packet Format The Extended Accessory Decoder Control Packet is included for the purpose of transmitting aspect control to signal decoders or data bytes to more complex accessory decoders. Each signal head can display one aspect at a time. {preamble} 0 10AAAAAA 0 0AAA0AA1 0 000XXXXX 0 EEEEEEEE 1 XXXXX is for a single head. A value of 00000 for XXXXX indicates the absolute stop aspect. All other aspects represented by the values for XXXXX are determined by the signaling system used and the prototype being modeled.

Parameters:

outputAddr - Address of accessory output, starting with 1 and a maximum of 2044

aspect - Aspect Number starting with 0 and a maximum of 31

accDecoderPkt

public static byte[] accDecoderPkt(int number,
                                   boolean closed)

Provide an accessory control packet via a simplified interface

Parameters:

number - Address of accessory output, starting with 1

closed - true if the output is to be configured to the "closed", a.k.a. the "normal" or "unset" position

accDecoderPktOpsMode

public static byte[] accDecoderPktOpsMode(int number,
                                          int cvNum,
                                          int data)

Provide an operation mode accessory control packet via a simplified interface

Parameters:

number - Address of accessory, starting with 1

cvNum - CV number to access

data - Data to be written

accDecoderPktOpsModeLegacy

public static byte[] accDecoderPktOpsModeLegacy(int number,
                                                int cvNum,
                                                int data)

Provide a legacy operation mode accessory control packet via a simplified interface

Parameters:

number - Address of accessory, starting with 1

cvNum - CV number to access

data - Data to be written

opsCvWriteByte

public static byte[] opsCvWriteByte(int address,
                                    boolean longAddr,
                                    int cvNum,
                                    int data)

speedStep128Packet

public static byte[] speedStep128Packet(int address,
                                        boolean longAddr,
                                        int speed,
                                        boolean fwd)

speedStep28Packet

public static byte[] speedStep28Packet(int address,
                                       boolean longAddr,
                                       int speed,
                                       boolean fwd)

From NMRA RP 9.2.1 A speed and direction instruction is used send information to motors connected to Multi Function Digital Decoders. Instruction "010" indicates a Speed and Direction Instruction for reverse operation and instruction "011" indicates a Speed and Direction Instruction for forward operation. In these instructions the data is used to control speed with bits 0-3 being defined exactly as in S-9.2 Section B. If Bit 1 of CV#29 has a value of one (1), then bit 4 is used as an intermediate speed step, as defined in S-9.2, Section B. If Bit 1 of CV#29 has a value of zero (0), then bit 4 shall 230 be used to control FL4. In this mode, Speed U0000 is stop, speed U0001 is emergency stop, speed U0010 is the first speed step and speed U1111 is full speed. This provides 14 discrete speed steps in each direction.

speedStep14Packet

public static byte[] speedStep14Packet(int address,
                                       boolean longAddr,
                                       int speed,
                                       boolean fwd,
                                       boolean F0)

function0Through4Packet

public static byte[] function0Through4Packet(int address,
                                             boolean longAddr,
                                             boolean f0,
                                             boolean f1,
                                             boolean f2,
                                             boolean f3,
                                             boolean f4)

function5Through8Packet

public static byte[] function5Through8Packet(int address,
                                             boolean longAddr,
                                             boolean f5,
                                             boolean f6,
                                             boolean f7,
                                             boolean f8)

function9Through12Packet

public static byte[] function9Through12Packet(int address,
                                              boolean longAddr,
                                              boolean f9,
                                              boolean f10,
                                              boolean f11,
                                              boolean f12)

function13Through20Packet

public static byte[] function13Through20Packet(int address,
                                               boolean longAddr,
                                               boolean f13,
                                               boolean f14,
                                               boolean f15,
                                               boolean f16,
                                               boolean f17,
                                               boolean f18,
                                               boolean f19,
                                               boolean f20)

function21Through28Packet

public static byte[] function21Through28Packet(int address,
                                               boolean longAddr,
                                               boolean f21,
                                               boolean f22,
                                               boolean f23,
                                               boolean f24,
                                               boolean f25,
                                               boolean f26,
                                               boolean f27,
                                               boolean f28)

analogControl

public static byte[] analogControl(int address,
                                   boolean longAddr,
                                   int function,
                                   int value)

Provide an NMRA analog control instruction

Note that the NMRA draft of Fall 2004 only defines the value of "1" for the "function parameter", calling that the value for "volume control". However, DCC systems in the wild have been observed to use 0x7F for the function byte for volume control.

Parameters:

address - DCC locomotive address

longAddr - true if this is a long address, false if short address

function - see note above

value - value to be sent in analog control instruction

consistControl

public static byte[] consistControl(int address,
                                    boolean longAddr,
                                    int consist,
                                    boolean directionNormal)

Provide an NMRA consist control instruction

Parameters:

address - DCC locomotive address

longAddr - true if this is a long address, false if short address

consist - the consist address to set for this locomotive. Send 00 as consist address if deleteing from consist.

directionNormal - true if the normal direction of travel for this address is the normal direction of travel for the consist.

format

public static String format(byte[] p)

Convert NMRA packet to a readable form