From 757b212c8158534fed091784e2ff00f27fbc0883 Mon Sep 17 00:00:00 2001 From: Neil McKechnie Date: Mon, 20 Mar 2023 17:23:50 +0000 Subject: [PATCH] Add HAL driver for CMRInet protocol --- IO_CMRI.cpp | 177 +++++++++++++++++++++++++++++ IO_CMRI.h | 320 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 497 insertions(+) create mode 100644 IO_CMRI.cpp create mode 100644 IO_CMRI.h diff --git a/IO_CMRI.cpp b/IO_CMRI.cpp new file mode 100644 index 0000000..e442d26 --- /dev/null +++ b/IO_CMRI.cpp @@ -0,0 +1,177 @@ +/* + * © 2023, Neil McKechnie. All rights reserved. + * + * This file is part of DCC++EX API + * + * This is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * It 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. + * + * You should have received a copy of the GNU General Public License + * along with CommandStation. If not, see . + */ + +#include "IO_CMRI.h" + +// Main loop function for CMRIbus. +// Work through list of nodes. For each node, in separate loop entries +// send initialisation message (once only); then send +// output message; then send prompt for input data, and +// process any response data received. +// When the slot time has finished, move on to the next device. +void CMRIbus::_loop(unsigned long currentMicros) { + + _currentMicros = currentMicros; + + while (_serial->available()) + processIncoming(); + + // Send any data that needs sending. + processOutgoing(); + +} + +void CMRIbus::processOutgoing() { + if (_currentNode == NULL) { + // If we're between read/write cycles then don't do anything else. + if (_currentMicros - _cycleStartTime < _cycleTime) return; + // ... otherwise start processing the first node in the list + _currentNode = _nodeListStart; + _transmitState = TD_INIT; + _cycleStartTime = _currentMicros; + } + if (_currentNode == NULL) return; + switch (_transmitState) { + case TD_IDLE: + case TD_INIT: + if (!_currentNode->isInitialised()) { + sendInitialisation(_currentNode); + _currentNode->setInitialised(); + _transmitState = TD_TRANSMIT; + break; + } + /* fallthrough */ + case TD_TRANSMIT: + sendData(_currentNode); + _transmitState = TD_PROMPT; + break; + case TD_PROMPT: + requestData(_currentNode); + _transmitState = TD_RECEIVE; + _timeoutStart = _currentMicros; // Start timeout on response + break; + case TD_RECEIVE: // Waiting for response / timeout + if (_currentMicros - _timeoutStart > _timeoutPeriod) { + // End of time slot allocated for responses. + _transmitState = TD_IDLE; + // Reset state of receiver + _receiveState = RD_SYN1; + // Move to next node + _currentNode = _currentNode->getNext(); + } + break; + } +} + +// Process any data bytes received from a CMRInode. +void CMRIbus::processIncoming() { + int data = _serial->read(); + if (data < 0) return; // No characters to read + + if (!_currentNode) return; // Not waiting for input, so ignore. + + uint8_t nextState = RD_SYN1; // default to resetting state machine + switch(_receiveState) { + case RD_SYN1: + if (data == SYN) nextState = RD_SYN2; + break; + case RD_SYN2: + if (data == SYN) nextState = RD_STX; + break; + case RD_STX: + if (data == STX) nextState = RD_ADDR; + break; + case RD_ADDR: + // If address doesn't match, then ignore everything until next SYN-SYN-STX. + if (data == _currentNode->getAddress() + 65) nextState = RD_TYPE; + break; + case RD_TYPE: + _receiveDataIndex = 0; // Initialise data pointer + if (data == 'R') nextState = RD_DATA; + break; + case RD_DATA: // data body + if (data == DLE) // escape next character + nextState = RD_ESCDATA; + else if (data == ETX) { // end of data + // End of data message. Protocol has all data in one + // message, so we don't need to wait any more. Allow + // transmitter to proceed with next node in list. + _currentNode = _currentNode->getNext(); + _transmitState = TD_IDLE; + } else { + // Not end yet, so save data byte + _currentNode->saveIncomingData(_receiveDataIndex++, data); + nextState = RD_DATA; // wait for more data + } + break; + case RD_ESCDATA: // escaped data byte + _currentNode->saveIncomingData(_receiveDataIndex++, data); + nextState = RD_DATA; + break; + } + _receiveState = nextState; +} + +// Constructor for CMRInode object +CMRInode::CMRInode(VPIN firstVpin, int nPins, uint8_t busNo, uint8_t address, char type, uint16_t inputs, uint16_t outputs) { + _firstVpin = firstVpin; + _nPins = nPins; + _busNo = busNo; + _address = address; + _type = type; + + switch (_type) { + case 'M': // SMINI, fixed 24 inputs and 48 outputs + _numInputs = 24; + _numOutputs = 48; + break; + case 'C': // CPNODE with 16 to 144 inputs/outputs using 8-bit cards + _numInputs = inputs; + _numOutputs = outputs; + break; + case 'N': // Classic USIC and SUSIC using 24 bit i/o cards + case 'X': // SUSIC using 32 bit i/o cards + default: + DIAG(F("CMRInode: bus:%d address:%d ERROR unsupported type %c"), _busNo, _address, _type); + return; // Don't register device. + } + if ((unsigned int)_nPins < _numInputs + _numOutputs) + DIAG(F("CMRInode: bus:%d address:%d WARNING number of Vpins does not cover all inputs and outputs"), _busNo, _address); + + // Allocate memory for states + _inputStates = (uint8_t *)calloc((_numInputs+7)/8, 1); + _outputStates = (uint8_t *)calloc((_numOutputs+7)/8, 1); + if (!_inputStates || !_outputStates) { + DIAG(F("CMRInode: ERROR insufficient memory")); + return; + } + + // Add this device to HAL device list + IODevice::addDevice(this); + + // Add CMRInode to CMRIbus object. + CMRIbus *bus = CMRIbus::findBus(_busNo); + if (bus != NULL) { + bus->addNode(this); + return; + } +} + +// Link to chain of CMRI bus instances +CMRIbus *CMRIbus::_busList = NULL; diff --git a/IO_CMRI.h b/IO_CMRI.h new file mode 100644 index 0000000..ce8afea --- /dev/null +++ b/IO_CMRI.h @@ -0,0 +1,320 @@ +/* + * © 2023, Neil McKechnie. All rights reserved. + * + * This file is part of DCC++EX API + * + * This is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * It 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. + * + * You should have received a copy of the GNU General Public License + * along with CommandStation. If not, see . + */ + +/* + * To define a CMRI bus, + * CMRIbus::create(bus, Serial3, 19200, cycletime); + * + * bus = 0-255 + * Serial3 = serial port to be used + * 19200 = baud rate (min 9600, max 115200) + * cycletime = minimum time between successive updates/reads of a node in millisecs + * + * Each bus must use a different serial port. + * + * To define a CMRI node and associate it with a CMRI bus, + * CMRInode:create(bus, address, type [, inputs, outputs]); + * + * bus = 0-255 + * address = 0-127 + * type = 'M' for SMINI (fixed 24 inputs and 48 outputs) + * 'C' for CPNODE (16 to 144 inputs/outputs in groups of 8) + * (other types are not supported at this time). + * inputs = number of inputs (CPNODE) + * outputs = number of outputs (CPNODE) + * + * Reference: "LCS-9.10.1 + * Layout Control Specification: CMRInet Protocol + * Version 1.1 December 2014." + */ + +#ifndef IO_CMRI_H +#define IO_CMRI_H + +#include "IODevice.h" + +/********************************************************************** + * CMRInode class + * + * This encapsulates the state associated with a single CMRI node, + * which includes the address type, number of inputs and outputs, and + * the states of the inputs and outputs. + **********************************************************************/ +class CMRInode : public IODevice { +private: + uint8_t _busNo; + uint8_t _address; + char _type; + CMRInode *_next = NULL; + uint8_t *_inputStates = NULL; + uint8_t *_outputStates = NULL; + uint16_t _numInputs = 0; + uint16_t _numOutputs = 0; + bool _initialised = false; + +public: + static void create(VPIN firstVpin, int nPins, uint8_t busNo, uint8_t address, char type, uint16_t inputs=0, uint16_t outputs=0) { + if (checkNoOverlap(firstVpin, nPins)) new CMRInode(firstVpin, nPins, busNo, address, type, inputs, outputs); + } + CMRInode(VPIN firstVpin, int nPins, uint8_t busNo, uint8_t address, char type, uint16_t inputs=0, uint16_t outputs=0); + + uint8_t getAddress() { + return _address; + } + CMRInode *getNext() { + return _next; + } + void setNext(CMRInode *node) { + _next = node; + } + bool isInitialised() { + return _initialised; + } + void setInitialised() { + _initialised = true; + } + + void _begin() { + _initialised = false; + } + + int _read(VPIN vpin) { + // Return current state from this device + uint16_t pin = vpin - _firstVpin; + if (pin < _numInputs) { + uint8_t mask = 1 << (pin & 0x7); + int index = pin / 8; + return (_inputStates[index] & mask) != 0; + } else + return 0; + } + + void _write(VPIN vpin, int value) { + // Update current state for this device, in preparation the bus transmission + uint16_t pin = vpin - _firstVpin - _numInputs; + if (pin < _numOutputs) { + uint8_t mask = 1 << (pin & 0x7); + int index = pin / 8; + if (value) + _outputStates[index] |= mask; + else + _outputStates[index] &= ~mask; + } + } + + void saveIncomingData(uint8_t index, uint8_t data) { + if (index < (_numInputs+7)/8) + _inputStates[index] = data; + } + + uint8_t getOutputStates(uint8_t index) { + if (index < (_numOutputs+7)/8) + return _outputStates[index]; + else + return 0; + } + + uint16_t getNumInputs() { + return _numInputs; + } + + uint16_t getNumOutputs() { + return _numOutputs; + } + + char getType() { + return _type; + } + + uint8_t getBusNumber() { + return _busNo; + } + + void _display() override { + DIAG(F("CMRInode type:'%c' configured on bus:%d address:%d VPINs:%u-%u (in) %u-%u (out)"), + _type, _busNo, _address, _firstVpin, _firstVpin+_numInputs-1, + _firstVpin+_numInputs, _firstVpin+_numInputs+_numOutputs-1); + } + +}; + +/********************************************************************** + * CMRIbus class + * + * This encapsulates the properties state of the bus and the + * transmission and reception of data across that bus. Each CMRIbus + * object owns a set of CMRInode objects which represent the nodes + * attached to that bus. + **********************************************************************/ +class CMRIbus : public IODevice { +private: + // Here we define the device-specific variables. + uint8_t _busNo; + HardwareSerial *_serial; + unsigned long _baud; + CMRInode *_nodeListStart = NULL, *_nodeListEnd = NULL; + CMRInode *_currentNode = NULL; + // Transmitter state machine states + enum {TD_IDLE, TD_INIT, TD_TRANSMIT, TD_PROMPT, TD_RECEIVE}; + uint8_t _transmitState = TD_IDLE; + // Receiver state machine states. + enum {RD_SYN1, RD_SYN2, RD_STX, RD_ADDR, RD_TYPE, + RD_DATA, RD_ESCDATA, RD_SKIPDATA, RD_SKIPESCDATA, RD_ETX}; + uint8_t _receiveState = RD_SYN1; + uint16_t _receiveDataIndex = 0; // Index of next data byte to be received. + CMRIbus *_nextBus = NULL; // Pointer to next bus instance in list. + unsigned long _cycleStartTime = 0; + unsigned long _timeoutStart = 0; + unsigned long _cycleTime; // target time between successive read/write cycles, microseconds + uint32_t _timeoutPeriod; // timeout on read responses, in microseconds. + unsigned long _currentMicros; // last value of micros() from _loop function. + + static CMRIbus *_busList; // linked list of defined bus instances + + // Definition of special characters in CMRInet protocol + enum : uint8_t { + STX = 0x02, + ETX = 0x03, + DLE = 0x10, + SYN = 0xff, + }; + +public: + static void create(uint8_t busNo, HardwareSerial &serial, unsigned long baud, uint16_t cycleTimeMS = 500) { + new CMRIbus(busNo, serial, baud, cycleTimeMS); + } + + // Add new CMRInode to the list of nodes for this bus. + void addNode(CMRInode *newNode) { + if (!_nodeListStart) + _nodeListStart = newNode; + if (!_nodeListEnd) + _nodeListEnd = newNode; + else + _nodeListEnd->setNext(newNode); + } + +protected: + CMRIbus(uint8_t busNo, HardwareSerial &serial, unsigned long baud, uint16_t cycleTimeMS) { + _busNo = busNo; + _serial = &serial; + _baud = baud; + _cycleTime = cycleTimeMS * 1000UL; // convert from milliseconds to microseconds. + + // Max message length is 256+6=262 bytes. + // Each byte is one start bit, 8 data bits and 1 stop bit = 10 bits per byte. + // Calculate timeout based on double this time. + _timeoutPeriod = 2 * 10 * 262 * 1000UL / (_baud / 1000); + //DIAG(F("Timeout=%l"), _timeoutPeriod); + + // Add device to HAL device chain + IODevice::addDevice(this); + + // Add bus to CMRIbus chain. + _nextBus = _busList; + _busList = this; + } + + // Device-specific initialisation + void _begin() override { + // Some sources quote one stop bit, some two. + _serial->begin(_baud, SERIAL_8N1); +#if defined(DIAG_IO) + _display(); +#endif + } + + void _loop(unsigned long currentMicros) override; + + // Display information about the device. + void _display() override { + DIAG(F("CMRIbus %d configured, speed=%d baud, cycle=%d ms"), _busNo, _baud, _cycleTime/1000); + } + + // Locate CMRInode object with specified address. + CMRInode *findNode(uint8_t address) { + for (CMRInode *node = _nodeListStart; node != NULL; node = node->getNext()) { + if (node->getAddress() == address) + return node; + } + return NULL; + } + + // Send output data to the bus for nominated CMRInode + bool sendData(CMRInode *node) { + uint16_t numDataBytes = (node->getNumOutputs()+7)/8; + _serial->write(SYN); + _serial->write(SYN); + _serial->write(STX); + _serial->write(node->getAddress() + 65); + _serial->write('T'); // T for Transmit data message + for (uint8_t index=0; indexgetOutputStates(index); + if (value == DLE || value == STX || value == ETX) _serial->write(DLE); + _serial->write(value); + } + _serial->write(ETX); + return true; + } + + // Send request for input data to nominated CMRInode. + bool requestData(CMRInode *node) { + _serial->write(SYN); + _serial->write(SYN); + _serial->write(STX); + _serial->write(node->getAddress() + 65); + _serial->write('P'); // P for Poll message + _serial->write(ETX); + return true; + } + + bool sendInitialisation(CMRInode *node) { + _serial->write(SYN); + _serial->write(SYN); + _serial->write(STX); + _serial->write(node->getAddress() + 65); + _serial->write('I'); // I for initialise message + _serial->write(node->getType()); // NDP + _serial->write(0); // dH + _serial->write(0); // dL + _serial->write(0); // NS + _serial->write(ETX); + return true; + } + + // Process any data bytes received from a CMRInode. + void processIncoming(); + + // Process any outgoing traffic that is due. + void processOutgoing(); + +public: + uint8_t getBusNumber() { + return _busNo; + } + + static CMRIbus *findBus(uint8_t busNo) { + for (CMRIbus *bus=_busList; bus!=NULL; bus=bus->_nextBus) { + if (bus->_busNo == busNo) return bus; + } + return NULL; + } +}; + +#endif // IO_CMRI_H \ No newline at end of file