rp2da2.rp2dcc.dcc_rc_pio.RailComRead

class documentation

class RailComRead(Device):

Constructor: RailComRead(dev_name, cu_sm_num, rc_rx_pin, cu_pin, dcc_pin)

The RailCom Reader class

This class schedules and executes RailCom datagram read activities during the cutout period. During the cutout the DCC power signal is ceased and the two DCC lines are short circuited allowing the RailCom current signal to be generated and detected. On the command station the cutout is instigated by the enable signal to the DRV8874 being set low. This cutout signal being low is used directly when detecting on the command station. A remote block detector monitors the DCC power to detect the cutout.

A RailCom reader object works on either on Channel 1 (block) or Channel 2 (central/global) but not both.

Channel 1 is used for block occupancy detection and usually the detector runs on a detector local to the block. Channel 2 is used for command responses and other decoder specific information. It only runs on the command station.

On the command station, as far as this class is concerned, the cutout (DRV8874 enable pin) is used as an input.

The RailCom detector output is high for no current detected and low for current detected. During the cutout period it will be high except when a RailCom encoder (e.g. DCC decoder) is actively transmitting.

Each RailCom reader uses two PIO state machines. One times the cutout and the second is the serial RailCom message receiver.

A PIO block has 4 state machines and can run two readers. The The cutout timers will be on the state machine numbers 0 & 2 of the PIO block and the associated receivers on state machine numbers 1 & 3. (Note that MicroPython numbers all state machines sequentially from 0 - e.g. it refers to the first state machine on the second PIO as no. 4.)

The cutout state machine starts the RailCom receiver using an IRQ. Relative IRQ numbering is used. The first is no 5 which will be used by state machine 0. State machine 2 will use IRQ 7.

At the end of the channel window the PIO state machine raises an application interrupt to initate reading the state machine FIFO buffer.

Static Method	`hw4_2_6b`	Translate Hamming weight 4 byte to 6 bit
Method	`__init__`	RailCom class constructor
Constant	`ACK`	acknowledgement from decoder (may be used as padding)
Constant	`DG_RESP`	internally generated datagram containing protocol control byte
Constant	`ERR_CB`	Unexpected Control Byte (within datagram body)
Constant	`ERR_FE`	datagram format error (incomplete)
Constant	`ERR_ID`	Invalid datagram id
Constant	`ERR_OE`	Overrun error (no valid stop bit)
Constant	`ERR_PL`	Payload content validation error
Constant	`ERR_RESP`	unable to associate ch2 response with command
Constant	`ERR_WH`	raw data byte not valid Hamming 4 weight - weight high
Constant	`ERR_WL`	raw data byte not valid Hamming 4 weight - weight low
Constant	`GBL_DEVICE_TYPE`	Global detector device type
Constant	`IMP_ACK`	no explicit ACK but datagram received (implicit ACK)
Constant	`LCL_DEVICE_TYPE`	Local block detector device type
Constant	`NAK`	negative acknowledgement from decoder (may follow ACK!)
Constant	`PROT_BYTE`	List of protocol control bytes
Constant	`RES`	reserved
Method	`_cut_out1_bd`	The Cutout state machine monitor program (channel1 / block detect)
Method	`_cut_out2`	The Cutout state machine monitor program (channel2)
Method	`_rail_com_msg`	Process the RailCom Response
Method	`_read_isr`	Hard ISR to ensure restart asap after window end
Method	`_read_soft`	Soft PIO read ISR
Method	`_rx_gbl`	The RailCom data receiver state machine program
Method	`_rx_lcl`	The RailCom data receiver state machine program
Constant	`_H4LU`	Hamming Look Up Table
Instance Variable	`_gash`	Undocumented
Instance Variable	`_last_command`	Undocumented
Instance Variable	`_max_buf`	Undocumented
Instance Variable	`_min_buf`	Undocumented
Instance Variable	`_ql`	Undocumented
Instance Variable	`_rc`	Undocumented
Instance Variable	`_read_ref`	Undocumented
Instance Variable	`_rx`	Undocumented
Instance Variable	`_rx_buff`	Undocumented
Instance Variable	`_rx_raw`	Undocumented
Instance Variable	`_sm`	Undocumented
Instance Variable	`_smrx`	Undocumented

@staticmethod

def hw4_2_6b(rawd): ¶

Translate Hamming weight 4 byte to 6 bit

This translates the raw data byte as deserialised back to the 6 bit datagram component value or protocol control character. Two errors are possible. The raw value signifies an overrun error or the Hamming weight is not 4.

Parameters
rawd	Hamming Weight 4 byte input

Returns
the translated 6 bit value, control byte or error code.

def __init__(self, dev_name, cu_sm_num, rc_rx_pin, *, cu_pin=None, dcc_pin=None): ¶

RailCom class constructor

Constructs a reader for Channel 1 (local block detector) or Channel 2 (global detector) using two PIO state machines.

The cutout monitor state machine runs on the supplied state machine number. The receive state machine runs on the number + 1.

1 and only 1 of cu_pin or dcc_pin must be specified. If dcc_pin is specified, this is the DCC sense pin on a local detector. If cu_pin is specified this is the DRV8874 enable pin. Depending on which pin is specified a local or global detector is constructed.

N.B the pins work in opposite senses. DRV8874 enable is low during the cutout. The DCC power on pin is high during the cutout!

Parameters
dev_name	for channel 1 this will be the block name
cu_sm_num	state machine number for cut out scheduling - 4 or 6 if using the second PIO block
rc_rx_pin	the detector output pin (pin + 1 is the orientation detect pin)
cu_pin	cutout indicator (global detector)
dcc_pin	DCC sense (track power on or off - local detector)

ACK = ¶

acknowledgement from decoder (may be used as padding)

Value

const(128)

DG_RESP = ¶

internally generated datagram containing protocol control byte

Value

const(64)

ERR_CB = ¶

Unexpected Control Byte (within datagram body)

Value

const(137)

ERR_FE = ¶

datagram format error (incomplete)

Value

const(139)

ERR_ID = ¶

Invalid datagram id

Value

const(138)

ERR_OE = ¶

Overrun error (no valid stop bit)

Value

const(133)

ERR_PL = ¶

Payload content validation error

Value

const(140)

ERR_RESP = ¶

unable to associate ch2 response with command

Value

const(136)

ERR_WH = ¶

raw data byte not valid Hamming 4 weight - weight high

Value

const(132)

ERR_WL = ¶

raw data byte not valid Hamming 4 weight - weight low

Value

const(134)

GBL_DEVICE_TYPE = ¶

Global detector device type

Value

const('g')

IMP_ACK = ¶

no explicit ACK but datagram received (implicit ACK)

Value

const(135)

LCL_DEVICE_TYPE = ¶

Local block detector device type

Value

const('l')

NAK = ¶

negative acknowledgement from decoder (may follow ACK!)

Value

const(131)

PROT_BYTE = ¶

List of protocol control bytes

Value

(ACK, NAK)

RES = ¶

reserved

Value

const(130)

@rp2.asm_pio()

def _cut_out1_bd(): ¶

The Cutout state machine monitor program (channel1 / block detect)

This version is for use on a pico in use as an RailCom block detector. The cutout is detected by monitoring the DCC power on the track. This enables reading during the channel 1 window. The cutout timings in µs:

0 - Packet end trailing edge 28 - cutout start (monitored here) 28 + 47 = 75 - enable receiver for ch1 28 + 152 = 180 - disable receiver for ch1 (ch1 end @ 177, ch2 start 193) 28 + 446 = 474 cutout ends (timed in DCCGen)

The clock is 500 kHz. 2 µs per tick 7 instructions

Once the read ISR is triggered the program freezes until reset and restarted by the parent application.

@rp2.asm_pio()

def _cut_out2(): ¶

The Cutout state machine monitor program (channel2)

This runs at the command station and the cutout is generated by the DCCGen state machine. This enables reading during the channel 2 window. The cutout timings in µs:

0 - Packet end trailing edge 28 - cutout start (timed in DCCGen - monitored here) 28 + 152 = 180 - enable reciever (ch1 end @ 177, ch2 start 193) 28 + 152 + 280 = 460 application start read (ch2 end 454) 28 + 446 = 474 cutout ends (timed in DCCGen) 28 + 152 + 280 + 20 = 480 repeat wait for enable going low.

The clock is 250 kHz. 4 µs per tick

7 instructions used - main loop 117 ticks total

def _rail_com_msg(self, buffer): ¶

Process the RailCom Response

This must be overriden by a bound method in the inheriting class.

Raises
`NotImplemented error if not overriden`

def _read_isr(self, _): ¶

Hard ISR to ensure restart asap after window end

def _read_soft(self, last_command): ¶

Soft PIO read ISR

Read PIO FIFO into buffer. Needs to be soft for memoryviews to work Common to both channel 1 & 2.

The raw buffer is in words - bits 0 - 7 data byte as received bit 8 (the orientation bit) overrun error is reported as all '1's

There must be at least 1 entry in the buffer.

Parameters
last_command	the DCC command that caused the response.

@rp2.asm_pio(in_shiftdir=rp2.PIO.SHIFT_RIGHT, out_shiftdir=rp2.PIO.SHIFT_RIGHT, fifo_join=rp2.PIO.JOIN_RX)

def _rx_gbl(): ¶

The RailCom data receiver state machine program

This implements a simplified version of an asynchronous communications receiver as typically employed in a UART. There's no transmission function.

The receiver is enabled at the start of the channel window by another state machine setting the interrupt flag. It is disabled once the data has been read by the application, which restarts the state machine.

The first input pin is the 'or' of the two sides of the detector circuit. One side detects +ve going RailCom pulses and the second -ve going pulses. A RailCom pulse indicates a logic '0', the line idle (no RailCom current) is a logic '1'. Low indicates logic '0' and vice versa.

A second input pin is not used to determine the orientation and the code does not process it, thereby saving 3 instructions when compared with the local version. In other respects the code is identical.

The state machine clock is set at 16 x the bit rate. (4 MHz)

There's no programatic way back to the first instruction within the PIO program. The state machine is restarted by the controlling application externally forcing execution of a jump to the first instruction.

Reading is stopped if an overrun error occurs.

14 instructions

@rp2.asm_pio(in_shiftdir=rp2.PIO.SHIFT_RIGHT, out_shiftdir=rp2.PIO.SHIFT_RIGHT, fifo_join=rp2.PIO.JOIN_RX)

def _rx_lcl(): ¶

The RailCom data receiver state machine program

This implements a simplified version of an asynchronous communications receiver as typically employed in a UART. There's no transmission function.

The second input pin is the first comparator side. This may be used to determine which side is active, thus indicating which way the locomotive is facing relative to the track DCC.

The osr is used as an additional register. It's not in use for transmission.

The state machine clock is set at 16 x the bit rate. (4 MHz)

There's no programatic way back to the first instruction within the PIO program. The state machine is restarted by the controlling application externally forcing a reset.

Reading is stopped if an overrun error occurs.

17 instructions

_H4LU = ¶

Hamming Look Up Table

This translates the received Hamming 4 weighted byte back to the six bit group from the original datagram or one of the 6 special values. Applicable to Ch1 & Ch2. N.B. the 6 special values are not valid for Ch1.

See RCN-217 2.5.

Value

{172: 0,
 170: 1,
 169: 2,
 165: 3,
 163: 4,
 166: 5,
 156: 6,
...

_gash = ¶

Undocumented

_last_command = ¶

Undocumented

_max_buf: int = ¶

Undocumented

_min_buf: int = ¶

Undocumented

_ql: bool = ¶

Undocumented

_rc = ¶

Undocumented

_read_ref = ¶

Undocumented

_rx = ¶

Undocumented

_rx_buff = ¶

Undocumented

_rx_raw = ¶

Undocumented

_sm = ¶

Undocumented

_smrx = ¶

Undocumented