Model Railroad System  2.2.1
Public Member Functions | Public Attributes | Static Public Attributes | Private Member Functions | Private Attributes | List of all members
nce::NCE Class Reference

Main NCE Cab Bus interface class. More...

Public Member Functions

 NCE (name, port="/dev/ttyS0",...)
 Constructor. More...
 
 ~NCE ()
 The destructor restores the serial port's state and closes it. More...
 
 NOP ()
 NOP, dummy instruction. More...
 
 AssignLoco (locoaddress, cabnumber)
 Assign loco to cab. More...
 
 ReturnClock ()
 Returns the fast clock to the RS232 port in binary mode. More...
 
 StopClock ()
 Stops the scale time clock. More...
 
 StartClock ()
 Starts the scale time clock. More...
 
 SetClock (hours, minutes)
 Set the scale time clock. More...
 
 SetClockFormat (format)
 Set clock 12/24 hours. More...
 
 SetClockRatio (ratio)
 Set clock speed (ratio). More...
 
 DequeuePacket (locoaddress)
 Dequeue packet by loco addr. More...
 
 EnableMain ()
 Enable main trk, kill prog. More...
 
 ReturnAuxilaryInputUnit (cabnumber)
 Returns status of Auxilary Input Unit. More...
 
 DisableMain ()
 Kill main track, enable program track. More...
 
 Dummy ()
 Dummy instruction returns "!" followed by CR/LF. More...
 
 SetLocoSpeedMode (locoaddress, mode)
 Sets the speed mode of loco. More...
 
 WriteToRAM (address,...)
 Writes bytes to a command station RAM address. More...
 
 ReadFromRAM (address)
 Returns 16 bytes from a RAM address. More...
 
 WriteLCDLine3 (cabnumber, textline)
 Sends a message to LCD line 3 of a cab. More...
 
 WriteLCDLine4 (cabnumber, textline)
 Sends a message to LCD line 4 of a cab. More...
 
 WriteLCDRightLine2 (cabnumber, textline)
 Sends a message to the right side of LCD line 2 of a cab. More...
 
 WriteRAWPacket (sendtimes,...)
 Reads a raw packet to put in TEMP_Q. More...
 
 WriteOneByteToRAM (address, byte)
 Writes 1 byte to a command station RAM address. More...
 
 WriteTwoBytesToRAM (address, byte1, byte2)
 Writes 2 bytes to a command station RAM address. More...
 
 Write4BytesToRAM (address, byte1, byte2, byte3, byte4)
 Writes 4 bytes to a command station RAM address. More...
 
 Write8BytesToRAM (address,...)
 Writes 4 bytes to a command station RAM address. More...
 
 ReturnAuxilaryInputUnitShortForm (cabnumber)
 Returns status of Auxilary Input Unit, short form. More...
 
 ExecuteMacro (macroNumber)
 Executes a previously defined macro for route control. More...
 
 ReadOneByteFromRAM (address)
 Reads 1 byte from a command station RAM address. More...
 
 ProgramMode ()
 Enters Program track mode. More...
 
 NormalMode ()
 Returns from Program track mode. More...
 
 WriteCVInPagedMode (address, data)
 Writes a CV in paged mode. More...
 
 ReadCVInPagedMode (address)
 Reads a CV in paged mode. More...
 
 SetLocomotiveSpeedAndDirection (locoaddress, ssm, dir, speed)
 Set locomotive speed and direction. More...
 
 SetLocomotiveFunctionsGroup1 (locoaddress, f0, f1, f2, f3, f4)
 Set locomotive functions, group 1. More...
 
 SetLocomotiveFunctionsGroup2 (locoaddress, f5, f6, f7, f8)
 Set locomotive functions, group 2. More...
 
 SetLocomotiveFunctionsGroup3 (locoaddress, f9, f10, f11, f12)
 Set locomotive functions, group 3. More...
 
 AddLocomotiveToMultiUnit (locoaddress, mtr, samedirection)
 Add locomotive to Multi-Unit. More...
 
 RemoveLocomotiveFromMultiUnit (locoaddress, mtr)
 Remove locomotive to Multi-Unit. More...
 
 AddLeadLocomotiveToMultiUnit (locoaddress, mtr, samedirection)
 Add lead locomotive to Multi-Unit. More...
 
 AddRearLocomotiveToMultiUnit (locoaddress, mtr, samedirection)
 Add rear locomotive to Multi-Unit. More...
 
 ChangeMomentumLevel (locoaddress, newlevel)
 Change momentum level for loco or consist. More...
 
 WriteRAWTrackPacket (...)
 Reads a raw packet to put in TRK_Q. More...
 
 WriteRegister (register, data)
 Writes a register. More...
 
 ReadRegister (register)
 Read a register. More...
 
 WriteCVInDirectMode (address, data)
 Writes a CV in direct mode. More...
 
 ReadCVInDirectMode (address)
 Reads a CV in direct mode. More...
 
 SoftwareVersion ()
 Read software version number. More...
 
 SoftReset ()
 Soft reset of command station. More...
 
 HardReset ()
 Hard reset of command station. More...
 
 MacroCommand (address, macronumber)
 Assign address to macro. More...
 
 AccessoryDecoderOperation (address, activateOutput)
 Accessory decoder operation request. More...
 
 SetSignalAspect (address, aspectBits)
 Set signal aspect. More...
 
 OperatingModeProgrammingByteModeWrite (locoaddress, cv, data)
 Operating mode programming byte mode write. More...
 
 OperatingModeAccessoryProgrammingByteModeWrite (address, cv, data)
 Operating mode accessory programming byte mode write. More...
 
 SetCabBusAddressOfUSBBoard (cabaddress)
 Set the cab bus address of the USB board. More...
 
 SetBinaryCommandEchoMode (mode)
 Set binary command echo mode. More...
 

Public Attributes

 ttyfd
 Terminal file descriptor. More...
 

Static Public Attributes

static NumberOfBytesReturned
 Array containing the number of bytes expected for each command. More...
 

Private Member Functions

 _transmit (themessage)
 Transmit a message. More...
 
 _readevent ()
 Read event handler, toggle timeout flag. More...
 
 _timeoutevent ()
 Timeout event handler, toggle timeout flag. More...
 
 _readbyte (thebytevar, timeout=5)
 Read next available byte or return false. More...
 
 _readresponse (bufferVar, expectnumberofbytes)
 Read a response message. More...
 
 _sendMessageAndReturnResponse (message)
 Send a message and return a response. More...
 
 _explodechars (text)
 Explode text into ASCII character codes. More...
 

Private Attributes

 _timeout
 Timeout or data available flag. More...
 

Detailed Description

Main NCE Cab Bus interface class.

This class implements the interface logic to connect to the NCE Cab Bus.

Parameters
portName of the serial port connected to the NCE Cab Bus.
...Options:
  • -baud Data rate, readonly, defaults to 9600, can be one of 9600 or 19200.
Author
Robert Heller <heller@deepsoft.com>

Constructor & Destructor Documentation

◆ NCE()

nce::NCE::NCE ( name  ,
port  = "/dev/ttyS0",
  ... 
)

Constructor.

Parameters
portName of the serial port connected to the NCE Cab Bus.
...Options:
  • -baud Data rate, readonly, defaults to 9600, can be one of 9600 or 19200.

◆ ~NCE()

nce::NCE::~NCE ( )

The destructor restores the serial port's state and closes it.

Member Function Documentation

◆ _explodechars()

nce::NCE::_explodechars ( text  )
private

Explode text into ASCII character codes.

◆ _readbyte()

nce::NCE::_readbyte ( thebytevar  ,
timeout  = 5 
)
private

Read next available byte or return false.

Parameters
thebytevarName of a variable to receive the byte.
timeoutTimeout in seconds.

If there is a defined external read event handler, the timeout parameter is ignored and false is returned if there are no bytes available. The presumption is that the read is being called from event handler and that means that there is data available.

◆ _readevent()

nce::NCE::_readevent ( )
private

Read event handler, toggle timeout flag.

◆ _readresponse()

nce::NCE::_readresponse ( bufferVar  ,
expectnumberofbytes   
)
private

Read a response message.

◆ _sendMessageAndReturnResponse()

nce::NCE::_sendMessageAndReturnResponse ( message  )
private

Send a message and return a response.

◆ _timeoutevent()

nce::NCE::_timeoutevent ( )
private

Timeout event handler, toggle timeout flag.

◆ _transmit()

nce::NCE::_transmit ( themessage  )
private

Transmit a message.

◆ AccessoryDecoderOperation()

nce::NCE::AccessoryDecoderOperation ( address  ,
activateOutput   
)

Accessory decoder operation request.

Parameters
addressAccessory address (not in DCC format).
activateOutputOutput on or off.
Returns
The response message.

◆ AddLeadLocomotiveToMultiUnit()

nce::NCE::AddLeadLocomotiveToMultiUnit ( locoaddress  ,
mtr  ,
samedirection   
)

Add lead locomotive to Multi-Unit.

Parameters
locoaddressLocomotive address.
mtrMulti-Unit address.
samedirectionThe locomotive direction is the same as the consist direction.
Returns
The response message.

◆ AddLocomotiveToMultiUnit()

nce::NCE::AddLocomotiveToMultiUnit ( locoaddress  ,
mtr  ,
samedirection   
)

Add locomotive to Multi-Unit.

Parameters
locoaddressLocomotive address.
mtrMulti-Unit address.
samedirectionThe locomotive direction is the same as the consist direction.
Returns
The response message.

◆ AddRearLocomotiveToMultiUnit()

nce::NCE::AddRearLocomotiveToMultiUnit ( locoaddress  ,
mtr  ,
samedirection   
)

Add rear locomotive to Multi-Unit.

Parameters
locoaddressLocomotive address.
mtrMulti-Unit address.
samedirectionThe locomotive direction is the same as the consist direction.
Returns
The response message.

◆ AssignLoco()

nce::NCE::AssignLoco ( locoaddress  ,
cabnumber   
)

Assign loco to cab.

From Bincmds.pdf: Loco address for this command is always 2 bytes. The first byte is zero in the case of a short address. If the address is long then bits 6,7 of first byte must be set to 1

Parameters
locoaddressLoco address (0-9999).
cabnumberCab number (0-63)
Returns
The response message.

◆ ChangeMomentumLevel()

nce::NCE::ChangeMomentumLevel ( locoaddress  ,
newlevel   
)

Change momentum level for loco or consist.

Parameters
locoaddressLocomotive or consist address.
newlevelNew momentum level (0-9).
Returns
The response message.

◆ DequeuePacket()

nce::NCE::DequeuePacket ( locoaddress  )

Dequeue packet by loco addr.

Reads loco address from BIN_BUFF, finds the corresponding entry in TRK_Q and deletes the packet from the TRK_Q.

Parameters
locoaddressLoco address (0-9999).
Returns
The response message.

◆ DisableMain()

nce::NCE::DisableMain ( )

Kill main track, enable program track.

Returns
The response message.

◆ Dummy()

nce::NCE::Dummy ( )

Dummy instruction returns "!" followed by CR/LF.

Returns
The response message.

◆ EnableMain()

nce::NCE::EnableMain ( )

Enable main trk, kill prog.

Returns
The response message.

◆ ExecuteMacro()

nce::NCE::ExecuteMacro ( macroNumber  )

Executes a previously defined macro for route control.

Parameters
macroNumberThe macro number.
Returns
The response message.

◆ HardReset()

nce::NCE::HardReset ( )

Hard reset of command station.

Clears all RAM and resets command station to original fac defaults. All stored information is destroyed Note: the baud rate will be set to 9600

◆ MacroCommand()

nce::NCE::MacroCommand ( address  ,
macronumber   
)

Assign address to macro.

Parameters
addressAccessory address (not in DCC format).
macronumberNCE macro number (0-255).
Returns
The response message.

◆ NOP()

nce::NCE::NOP ( )

NOP, dummy instruction.

Returns
The response message.

◆ NormalMode()

nce::NCE::NormalMode ( )

Returns from Program track mode.

Power is restored to mainline and removed from program track. The queues are reinitialized for normal operation.

Returns
The response message.

◆ OperatingModeAccessoryProgrammingByteModeWrite()

nce::NCE::OperatingModeAccessoryProgrammingByteModeWrite ( address  ,
cv  ,
data   
)

Operating mode accessory programming byte mode write.

Parameters
addressAccessory address.
cvCV to set.
dataData to set.
Returns
The response message.

◆ OperatingModeProgrammingByteModeWrite()

nce::NCE::OperatingModeProgrammingByteModeWrite ( locoaddress  ,
cv  ,
data   
)

Operating mode programming byte mode write.

Parameters
locoaddressLocomotive address.
cvCV to set.
dataData to set.
Returns
The response message.

◆ ProgramMode()

nce::NCE::ProgramMode ( )

Enters Program track mode.

Power is removed from mainline and applied to program track. The queues are formatted to send reset packets.

Returns
The response message.

◆ ReadCVInDirectMode()

nce::NCE::ReadCVInDirectMode ( address  )

Reads a CV in direct mode.

Parameters
addressCV address.
Returns
The register value, -1 for unsupported or -2 for bad CV number.

◆ ReadCVInPagedMode()

nce::NCE::ReadCVInPagedMode ( address  )

Reads a CV in paged mode.

Parameters
addressCV address.
Returns
The register value, -1 for unsupported or -2 for bad CV number.

◆ ReadFromRAM()

nce::NCE::ReadFromRAM ( address  )

Returns 16 bytes from a RAM address.

Parameters
addressAddress to start reading from.
Returns
The response message (16 data bytes).

◆ ReadOneByteFromRAM()

nce::NCE::ReadOneByteFromRAM ( address  )

Reads 1 byte from a command station RAM address.

Parameters
addressRAM address.
Returns
The data byte.

◆ ReadRegister()

nce::NCE::ReadRegister ( register  )

Read a register.

Parameters
registerThe register to read from.
Returns
The register value, -1 for unsupported or -2 for bad register number.

◆ RemoveLocomotiveFromMultiUnit()

nce::NCE::RemoveLocomotiveFromMultiUnit ( locoaddress  ,
mtr   
)

Remove locomotive to Multi-Unit.

Parameters
locoaddressLocomotive address.
mtrMulti-Unit address (not used).
Returns
The response message.

◆ ReturnAuxilaryInputUnit()

nce::NCE::ReturnAuxilaryInputUnit ( cabnumber  )

Returns status of Auxilary Input Unit.

Returns four bytes. The first 2 bytes are a bit map of the 14 AIU inputs. The last 2 bytes are a bit map of any changes since this command was last given. If the cab is greater than 63 it will be "forced" to 0. The first time this command is given for a cab after the command station is powered up or reset the change bytes will be 0x3fff.

Parameters
cabnumberCab number (0-63)
Returns
A list of two values, the bit map of values and the changed bitmap of values or the list {-1 -1} if the operation is unsupported.

◆ ReturnAuxilaryInputUnitShortForm()

nce::NCE::ReturnAuxilaryInputUnitShortForm ( cabnumber  )

Returns status of Auxilary Input Unit, short form.

This is a short form of CMD 0x8A. It returns only the first 2 bytes of command 0x8A. The 2 bytes are a bit map of the 14 AIU inputs. If the cab is greater than 63 it will be "forced" to 0.

Parameters
cabnumberCab number (0-63)
Returns
The bit map of values or -1 if the operation is unsupported.

◆ ReturnClock()

nce::NCE::ReturnClock ( )

Returns the fast clock to the RS232 port in binary mode.

Returns
The response message (hours, minutes).

◆ SetBinaryCommandEchoMode()

nce::NCE::SetBinaryCommandEchoMode ( mode  )

Set binary command echo mode.

Parameters
modeMode to set: 0 = no echo, 1 = echo 1st byte of command, or 2 = echo entire command.
Returns
The response message.

◆ SetCabBusAddressOfUSBBoard()

nce::NCE::SetCabBusAddressOfUSBBoard ( cabaddress  )

Set the cab bus address of the USB board.

Parameters
cabaddressCab address.
Returns
The response message.

◆ SetClock()

nce::NCE::SetClock ( hours  ,
minutes   
)

Set the scale time clock.

Parameters
hoursHours (0-23).
minutesMinutes (0-59).
Returns
The response message.

◆ SetClockFormat()

nce::NCE::SetClockFormat ( format  )

Set clock 12/24 hours.

Parameters
formatClock format flag: true for 24 hour format, false for 12 hour format.
Returns
The response message.

◆ SetClockRatio()

nce::NCE::SetClockRatio ( ratio  )

Set clock speed (ratio).

Parameters
ratioScale clock ratio, 1-25.
Returns
The response message.

◆ SetLocomotiveFunctionsGroup1()

nce::NCE::SetLocomotiveFunctionsGroup1 ( locoaddress  ,
f0  ,
f1  ,
f2  ,
f3  ,
f4   
)

Set locomotive functions, group 1.

Parameters
addressLocomotive address.
f0Function 0.
f1Function 1.
f2Function 2.
f3Function 3.
f4Function 4.
Returns
The response message.

◆ SetLocomotiveFunctionsGroup2()

nce::NCE::SetLocomotiveFunctionsGroup2 ( locoaddress  ,
f5  ,
f6  ,
f7  ,
f8   
)

Set locomotive functions, group 2.

Parameters
addressLocomotive address.
f5Function 5.
f6Function 6.
f7Function 7.
f8Function 7.
Returns
The response message.

◆ SetLocomotiveFunctionsGroup3()

nce::NCE::SetLocomotiveFunctionsGroup3 ( locoaddress  ,
f9  ,
f10  ,
f11  ,
f12   
)

Set locomotive functions, group 3.

Parameters
addressLocomotive address.
f9Function 9.
f10Function 10.
f11Function 11.
f12Function 12.
Returns
The response message.

◆ SetLocomotiveSpeedAndDirection()

nce::NCE::SetLocomotiveSpeedAndDirection ( locoaddress  ,
ssm  ,
dir  ,
speed   
)

Set locomotive speed and direction.

Parameters
locoaddressLocomotive address.
ssmSpeed mode (either S28 or S128).
dirDirection (either Forward or Reverse).
speedLocomotive speed (0-28, 0-128, or 255 (means emergency stop)).
Returns
The response message.

◆ SetLocoSpeedMode()

nce::NCE::SetLocoSpeedMode ( locoaddress  ,
mode   
)

Sets the speed mode of loco.

Parameters
locoaddressLoco address (0-9999).
modeSpeed step mode, one of S14, S28, or S128.
Returns
The response message.

◆ SetSignalAspect()

nce::NCE::SetSignalAspect ( address  ,
aspectBits   
)

Set signal aspect.

Parameters
addressAccessory address (not in DCC format).
aspectBitsSignal aspect bit mask.
Returns
The response message.

◆ SoftReset()

nce::NCE::SoftReset ( )

Soft reset of command station.

Sets command Station to power up condition.

◆ SoftwareVersion()

nce::NCE::SoftwareVersion ( )

Read software version number.

Returns
The software version as three bytes.

◆ StartClock()

nce::NCE::StartClock ( )

Starts the scale time clock.

Returns
The response message.

◆ StopClock()

nce::NCE::StopClock ( )

Stops the scale time clock.

Returns
The response message.

◆ Write4BytesToRAM()

nce::NCE::Write4BytesToRAM ( address  ,
byte1  ,
byte2  ,
byte3  ,
byte4   
)

Writes 4 bytes to a command station RAM address.

Parameters
addressRAM address.
byte1First byte to write.
byte2Second byte to write.
Returns
The response message.

◆ Write8BytesToRAM()

nce::NCE::Write8BytesToRAM ( address  ,
  ... 
)

Writes 4 bytes to a command station RAM address.

Parameters
addressRAM address.
byte1First byte to write.
byte2Second byte to write.
Returns
The response message.

◆ WriteCVInDirectMode()

nce::NCE::WriteCVInDirectMode ( address  ,
data   
)

Writes a CV in direct mode.

Parameters
addressCV address.
dataData to write.
Returns
The response message.

◆ WriteCVInPagedMode()

nce::NCE::WriteCVInPagedMode ( address  ,
data   
)

Writes a CV in paged mode.

Parameters
addressCV address.
dataData to write.
Returns
The response message.

◆ WriteLCDLine3()

nce::NCE::WriteLCDLine3 ( cabnumber  ,
textline   
)

Sends a message to LCD line 3 of a cab.

Parameters
cabnumberCab Number (0-63).
textlineA string of 16 printable characters.
Returns
The response message.

◆ WriteLCDLine4()

nce::NCE::WriteLCDLine4 ( cabnumber  ,
textline   
)

Sends a message to LCD line 4 of a cab.

Parameters
cabnumberCab Number (0-63).
textlineA string of 16 printable characters.
Returns
The response message.

◆ WriteLCDRightLine2()

nce::NCE::WriteLCDRightLine2 ( cabnumber  ,
textline   
)

Sends a message to the right side of LCD line 2 of a cab.

Parameters
cabnumberCab Number (0-63).
textlineA string of 8 printable characters.
Returns
The response message.

◆ WriteOneByteToRAM()

nce::NCE::WriteOneByteToRAM ( address  ,
byte   
)

Writes 1 byte to a command station RAM address.

Parameters
addressRAM address.
byteByte to write.
Returns
The response message.

◆ WriteRAWPacket()

nce::NCE::WriteRAWPacket ( sendtimes  ,
  ... 
)

Reads a raw packet to put in TEMP_Q.

Parameters
sendtimesNumber of times to send packet, 0 means don't send it. 255 is the same as 254 (system limitation).
...Packet bytes to send, 3 to 6 bytes.
Returns
The response message.

◆ WriteRAWTrackPacket()

nce::NCE::WriteRAWTrackPacket (   ...)

Reads a raw packet to put in TRK_Q.

Parameters
...Packet bytes to send, 3 to 5 bytes.
Returns
The response message.

◆ WriteRegister()

nce::NCE::WriteRegister ( register  ,
data   
)

Writes a register.

Parameters
registerThe register to write to.
dataThe data to write.
Returns
The response message.

◆ WriteToRAM()

nce::NCE::WriteToRAM ( address  ,
  ... 
)

Writes bytes to a command station RAM address.

Parameters
addressAddress to start writing to.
...Bytes to write (upto 16).
Returns
The response message.

◆ WriteTwoBytesToRAM()

nce::NCE::WriteTwoBytesToRAM ( address  ,
byte1  ,
byte2   
)

Writes 2 bytes to a command station RAM address.

Parameters
addressRAM address.
byte1First byte to write.
byte2Second byte to write.
Returns
The response message.

Member Data Documentation

◆ _timeout

nce::NCE::_timeout
private

Timeout or data available flag.

◆ NumberOfBytesReturned

nce::NCE::NumberOfBytesReturned
static

Array containing the number of bytes expected for each command.

◆ ttyfd

nce::NCE::ttyfd

Terminal file descriptor.