A model railway automation project part of the GenericJMRIdecoder project (https://github.com/jonasbjurel/GenericJMRIdecoder)
Copyright (c) 2021 Jonas Bjurel (jonas.bjurel@hotmail.com)
Licensed under the Apache License, Version 2.0 (the "License");
You may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law and agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
genericIOSatelite is a model railway sensor- and actuator project part of the the GenericJMRIdecoder project providing railway model automation using the JMRI open-source project and the GenericJMRIdecoder - see https://github.com/jonasbjurel/GenericJMRIdecoder
genericIOSatelite -- AKA Satelite provide actuator- and sensor
capabilities for use with model railways. It builds on an FPGA design,
and comes with a PCB and an Arduino ESP32 software library.
genericIOSatelite can be connected to a ESP32 GenericJMRIdecoder for
large scale sensor and actuator capabilities -- E.g., for sensing train
presence or maneuverings turnouts, servos or solenoids
Several genericIOSatelite (here after called Satelites) (up to
MAX_NO_OF_SAT_PER_CH) can be daisy chained in a loop for each Satelite
link. Each of the Satelites holds 4 actuator outputs, each of them
individually configured through Satelite link commands (E.g., PWM,
Pulses, and static low/high states). They also collect up to 8 sensor
inputs - transferred to the master through the Satelite link.
Satelite instructions, control information, alignment information, CRC checksums and Padding (E.g., sensor state to be filled in by the Satelites are pushed from the link master - A.
Satelites fill in the return information (E.g., Sensor state, remote CRC error indication, CRC checksum for the new datagram generated by the Satelite, and delivers it to the master - B.
This is a synchronous operation, and as the master pushes new data to the Satelites, it will synchronously receive Satelite data (E.g., sensor status from all the Satelites. B will not only contain feedback information, but also residues from the previous satellite orders - A.
ADDRESS N+1 ADDRESS N ADDRESS 0
Sense[0:7] Sense[0:7] Sense[0:7]
Act[0:3] ! Act[0:3] ! Act[0:3] !
^ ! ^ ! ^ !
! v ! v ! v
+-------------+ A +-+------+-+ A+B +-+------+-+ A+B +-+------+-+
! !--------/-------->! Satelite !--------/------>! Satelite !--------//---------! Satelite !--------+
! Link master ! +----------+ +----------+ N +----------+ !
! !<-------------------------------------/----------------------------------------------------------+
+-------------+ B
The Satelite link is based on the WS28XX defacto standard but deviates in a significant way in that the first Satelite doesn't latch on the first data on the line, instead commands traverse through the link loop in a transparent shift register fashion and gets latched by each Satelite when there is now activity (link low) for >=100 uS.
The symbol encoding is the following:
1: Link high: 600 ns, Link low: 650 ns (Cycle time 1250 ns).
0: Link high: 250 ns, Link low: 1000 ns (Cycle time 1250 ns).
The physical layer is LVLVDS (2.5 V LVDS)
The transport protocol representation is the following (First transmitted on the link first):
Link Mater out - A:
| Field/Bits | Description |
|---|---|
| [7:0] SensorVal-PAD | Shall be set to 0 |
| [7:0] ActVal[3] | Actuator value: meaning dependent on ActMode[3] |
| [7:0] ActVal[2] | Actuator value: meaning dependent on ActMode[2] |
| [7:0] ActVal[1] | Actuator value: meaning dependent on ActMode[1] |
| [7:0] ActVal[0] | Actuator value: meaning dependent on ActMode[0] |
| [2:0]ActMode[3] | Actuator Mode: SATMODE_LOW(0): logical low, SATMODE_HIGH(1): logical high, SATMODE_PWM1_25K(2): 1.25kHz PWM controlled by ActVal[3](%), SATMODE_PWM100(3): 100 Hz PWM controlled by ActVal[3](%), SATMODE_PULSE(4): Single High pulse controlled by ActVal[3](ms), SATMODE_PULSE_INV(5): Single Low pulse controlled by ActVal[3](ms) |
| [2:0]ActMode[2] | Actuator Mode: SATMODE_LOW(0): logical low, SATMODE_HIGH(1): logical high, SATMODE_PWM1_25K(2): 1.25kHz PWM controlled by ActVal[2](%), SATMODE_PWM100(3): 100 Hz PWM controlled by ActVal[2](%), SATMODE_PULSE(4): Single High pulse controlled by ActVal[2](ms), SATMODE_PULSE_INV(5): Single Low pulse controlled by ActVal[2](ms) |
| [2:0]ActMode[1] | Actuator Mode: SATMODE_LOW(0): logical low, SATMODE_HIGH(1): logical high, SATMODE_PWM1_25K(2): 1.25kHz PWM controlled by ActVal[1](%), SATMODE_PWM100(3): 100 Hz PWM controlled by ActVal[1](%), SATMODE_PULSE(4): Single High pulse controlled by ActVal[1](ms), SATMODE_PULSE_INV(5): Single Low pulse controlled by ActVal[1](ms) |
| [2:0]ActMode[0] | Actuator Mode: SATMODE_LOW(0): logical low, SATMODE_HIGH(1): logical high, SATMODE_PWM1_25K(2): 1.25kHz PWM controlled by ActVal[0](%), SATMODE_PWM100(3): 100 Hz PWM controlled by ActVal[0](%), SATMODE_PULSE(4): Single High pulse controlled by ActVal[0](ms), SATMODE_PULSE_INV(5): Single Low pulse controlled by ActVal[0](ms) |
| cmdcmdWdErr | Generatew a watchdog error in the feed-back fbWdErr message, this is nonintrusive and will not disable actuators. |
| cmdEnable | Enable Satelite: 1, Disable Satelite: 0, if disabled, the Satelite will set all actuators to 0 |
| cmdInvCrc | If set to 1, the Satelite will create an invalid CRC checksum towards the link master, if set to 0 correct CRC checksums will be generated. |
| startMark | Shall be set for the first Satelite datagram sent on the link (Satelite address 0), for following Satelite datagrams it shall be set to 0. This mark is set to allow each Satelite to understand where in the link-chain they sit (their address on the link), this is used for the CRC evaluation and creation. The Satelite closest to the link master's input (furthers away from the link masters ws28xx output) is designated address 0. |
| fbReserv-PAD[2] | Shall be set to 0 |
| fbWdErr-PAD | Shall be set to 0 |
| fbRemoteCrcErr-PAD | Shall be set to 0 |
| [3:0]CRC | CRC-4 checksum generated over the full Satelite datagram sent from Satelite link master, excluding the CRC-4 checksum it self. The CRC-4 checksum polynom is (x^4+x^1+x^0)(+)sateliteAddr[7:4](+)sateliteAddr[3:0]. |
Link Master in - B:
| Field/Bits | Description |
|---|---|
| [7:0]SensorVal | Sensor inputs, latched since previous link scan |
| [7:0]ActVal[3] | Don't care |
| [7:0]ActVal[2] | Don't care |
| [7:0]ActVal[1] | Don't care |
| [7:0]ActVal[0] | Don't care |
| [2:0]ActMode[3] | Don't care |
| [2:0]ActMode[2] | Don't care |
| [2:0]ActMode[1] | Don't care |
| [2:0]ActMode[0] | Don't care |
| cmdcmdWdErr | Don't care |
| cmdEnable | Don't care |
| cmdInvCrc | Don't care |
| startMark | Transparent - Can be checked by the link-master, should only be set for the first pulled Satelite (Address 0) |
| fbReserv[2] | Don't care. |
| fbWdErr | Set to 1 in case the Satelite has experienced a watchdog timeout |
| fbRemoteCrcErr | Set to 1 in case the Satelite experienced a RX CRC error on the Satelite datagram. |
| [3:0]CRC | CRC-4 checksum generated over the full Satelite datagram sent from the Satelite, excluding the CRC-4 checksum it self. The CRC-4 checksum polynom is (x^4+x^1+x^0)(+)sateliteAddr[7:4](+)sateliteAddr[3:0]. |
| I/O Name: | I/O | Lattice machxo2-1200 FPGAPin(QFP32) Pin: |
TinyFPGA AX PCB Pin: |
|---|---|---|---|
| ws2811wireIn + | I | 13 (LVDS 2.5V +) | 1 (LVDS 2.5V +) |
| ws2811wireIn - | I | 14 (LVDS 2.5V -) | 2 (LVDS 2.5V -) |
| sensorInput[0] | I | 20 | 5 |
| sensorInput[1] | I | 21 | 6 |
| sensorInput[2] | I | 23 | 7 |
| sensorInput[3] | I | 25 | 8 |
| sensorInput[4] | I | 26 | 9 |
| sensorInput[5] | I | 27 | 10 |
| sensorInput[6] | I | 28 | 11 |
| sensorInput[7] | I | 12 | 22 |
| ws2811wireOut + | O | 4 (LVDS 2.5V +) | 16 (LVDS 2.5V +) |
| ws2811wireOut - | O | 5 (LVDS 2.5V -) | 17 (LVDS 2.5V -) |
| actuators[0] | O | 11 | 21 |
| actuators[1] | O | 10 | 20 |
| actuators[2] | O | 9 | 19 |
| actuators[3] | O | 8 | 18 |
| Active (Scan- indication) |
O | 16 | 3 (Tiny FPGA LED) |
| Err (Error indi- cation, Watchdog- or CRC-Err) |
O | 17 | 4 |
The Satelite library consists of two classes:
-
The sateliteLink class which manages the low-level Satelite link (I.e. OSI L1, L2 and L3). It is responsible for the discovery- and topology management of Satelites sitting on the Satelite link, it is also responsible for scanning the link (providing instructions and pulling results from all the Satelites on a Satelite link), as well as for the integrity of the link. It interchanges raw data
from/to the satelite class objects of the Satelite link. The sateliteLink class has no, or very little knowledge around the functionality of the Satelites and their respective class-objects. The sateliteLink objects communicate with their child satelite class objects through shared memory, moreover the sateliteLink class objects create satelite class objects as part of the sateliteLink class auto-discovery process. A previously registered user call-back is called for every satelite object that is created from the auto-discovered Satelite, similarly if the sateliteLink decides to delete a satelite class object based on errors, or other blocking interventions - a call-back is sent to the user of the satelite class object. -
The satelite class which is responsible for the higher-level functionality of each satelite (OSI L4-L7). Each satelite class object gets created through its parent sateliteLink class object after the sateliteLink Auto discovery process, Satelite users get informed about the existence of a satelite through call-backs registered through the parent sateliteLink class object. The satelite class objects have methods for setting the actuators, receiving sensor values, and supervising the functionality and the integrity of each satelite.
This library allows the creation of multiple Satelite Link masters - providing that available resources allow for it, E.g. RMT channels, RMT memory blocks, etc. For each Link master (sateliteLink object) a maximum of MAX_NO_OF_SAT_PER_CH can be instantiated.
+--------+ 1:N +-------------+ 1:M +----------+ ! master !--//-->! Link master !--//-->! Satelite ! +--------+ +-------------+ +----------+
With "master" is meant an entity that may run multiple instances of this library, E.g., an ESP32 running the genericJMRIdecoder project Software found here: https://github.com/jonasbjurel/GenericJMRIdecoder, or otherwise. This is outside the scope for this description.
The Link master refers to the sateliteLink class referred to in this description.
The satelite refers to the satelite class and its object instantiations described in this description.
The sateliteLink- and the satelite class objects both have an administrative state and an operational state.
The administrative state can be one of either DISABLED or ENABLED. The administrative state is hierarchical and is a consequence of a user ordered change of the administrative state. It is hierarchical in the sense that the higher layer objects (I.e., sateliteLink) must be administratively enabled before the underlying objects (I.e., Satelites) can be administratively enabled, consequently a higher layer object cannot be disabled if not all underlying objects are disabled.
As long as the hierarchical rules of the administrative states are followed, an ordered change of the administrative state is always successful.
If an object is disabled, actions, feedback, and error supervision are disabled for that object, E.g., for Satelites this means that the actuators are disabled, no sensor data is fed back, etc.
Sometimes we refer to administrative blocking/de-blocking, blocked/de-blocked as the administrative state change actions and the administrative state.
The operational state reflects the operational status of an object, I.e., if it functions or not, in difference to the administrative state, the operational state is not hierarchical, and any object can change its operational state at any time depending on its operational status (it may though affect the operational status of underlying objects).
Another difference is that the administrative state only can assume distinct states, while the operative states can have multiple states at the same time.
The operational states can have a permutation of the following states:
-
"WORKING" - The object is fully working, cannot be combined with any other operational state attributes
-
"INIT" - The object is being initialized, can be combined with other operational state attributes
-
"DISABLE" - The object is disabled based on its administrative state, cannot be combined with other operational state attributes
-
"CTRLBLCK" - The object is control blocked as a higher layer object is not functioning (E.g. Operational state != "WORKING"), can be combined with other operational state attributes.
-
"ERRSEC" - The object has experienced errors that goes beyond the threshold set for one second, can be combined with other operational state attributes.
-
"FAIL" - The object has experienced a general failure, can be combined with other operational state attributes.
As an example of the "CTRLBLCK" operational state attribute, if a sateliteLink experiences an error leading to an operational state != "WORKING", all satellite objects belonging to that sateliteLink will assume the "CTRLBLCK" attribute as they cannot function without their parent sateliteLink functioning.
When a sateliteLink object has been in non "WORKING" state for 30
seconds (T_REESTABLISH_LINK_MS), it is assumed that the link topology
has changed, and a re-initialization will start. This means that all its
satelite objects are deleted, and a new sateliteLink Auto discovery will
be initiated (See further down on the matter of auto-discovery).
As this design is to be used for various sensor input and actuator output for model railway automation, errors in input and output can lead to unpredicted behaviour, collisions, and though not with catastrophic consequences - certainly with damage of material. This implementation is by no means redundant but aims to catch all faults that would lead to unpredicted behaviour, through error checks avoid that inputs and outputs are subject to faulty stimuli and transmission propagation. Through Cyclic Redundant Checksum of the transmitted orders- and feed-back, this implementation can detect a squelch spurious events. Furthermore, these error-detection mechanisms can be exercised in a "simulated fashion" such that non-intrusive self-tests can be run - exercising and validating the error supervision logic without impacting the operation.
The following error supervision is implemented.
Satelite link masters transmits datagrams to each Satelite on the link with a CRC-4 checksum calculated over each of the Satelite's datagram, hashed with each Satelites address.
As each Satelite receives the CRC-4 checksums, they validate the received CRC-4 checksum from the Link master (each individually hashed with its Satelite address) towards the Satelite's calculated datagram checksum (again hashed with it's Satelite address). If they match, the actuators are moved according to the actuator commands, if on the other hand there was a CRC error detected, they stay as they were before and the crcRemoteError bit is set towards the Link master such that the Link master has full visibility of the link performance.
Each Satelite transmits a CRC-4 checksum (hashed with its own address towards the Link master, such that the Link master can discriminate reliable sensor- and feed-back messages from those that contains errors.
The hashing of the CRC-4 checksum with each individual Satelite address (calculated from the Satelite Link's startMark) provides additional protection against misaddressed Satelites - both for actuator actions as well as for sensor feed-back.
Whenever a Satelite receives a datagram with invalid CRC checksum, the Actuator orders and other Satelite commands are ignored, and are left as they previously were set. Similarly, Satelite sensor data and other feed-back data are disregarded if the link-master detects a CRC error from that particular Satelite.
Each Satelite implements a watchdog monitoring the link scanning of the Satelite. If the link has not been scanned for 500 ms, the watchdog is triggered, disabling all the actuators for that particular Satelite. When triggered, the fbWdErr bit is set such that the master gets informed about the event at the next link-scan.
Performance data are collected from the link. Following performance data exist and can be retrieved through class methods:
-
Symbol error: The master has detected a symbol error on the receiving side.
-
Rx-size error: The master has detected that the size of a received datagram was wrong.
-
Timing violation: The link scan could not be performed within given link scan time.
-
Rx-CRC error: The master has received a datagram from a particular Satelite with wrong CRC-4 checksum.
-
Remote-CRC error: A particular Satelite has received a datagram with wrong CRC-4 checksum.
-
Watchdog error: The watchdog for a particular Satelite has been triggered.
All of the above errors are aggregated on a per sateliteLink object as well as per satelite object. If the sum of these errors exceeds a high threshold level during a second period, the respective object is deemed faulty and goes into operational state "ERRSEC", this operational state is ceased once the sum of errors during a second goes below a low threshold level.
The sateliteLink can auto discover the Satelites sitting on the link.
This is done by forcing the master to generate all faulty CRC-4
checksums on the transmitting side for MAX_NO_OF_SAT_PER_CH + 1
Satelites. Every Satelite on the link will respond with a remote CRC
error bit, for those data grams that has this bit set the master knows
that there is a corresponding Satelite, and for those datagrams that
doesn't have this bit set it knows there isn't a a corresponding
Satelite.
The master can perform Satelite self-tests. The self test is exercising the Satelites and master receiver's CRC-4 checksum detection, as well as the watchdog. The self-test is nonintrusive.
sateliteLink(uint8_t address_p, gpio_num_t txPin_p, gpio_num_t rxPin_p,
rmt_channel_t txCh_p, rmt_channel_t rxCh_p, uint8_t txRmtMemBank_p,
uint8_t rxRmtMemBank_p, UBaseType_t pollTaskPrio_p,
UBaseType_t pollTaskCore_p, uint8_t scanInterval_p)Description:
Creates a new sateliteLink object.
Parameters:
uint8_t address_p: The address of the sateliteLink, an arbitrary
number between 0 and 255.
gpio_num_t txPin_p: The Pin number for the link TX side
gpio_num_t rxPin_p: The Pin number for the link RX side
rmt_channel_t txCh_p: ESP RMT TX channel
rmt_channel_t rxCh_p: ESP RMT RX channel
uint8_t txRmtMemBank_p: ESP RMT TX memory bank
uint8_t rxRmtMemBank_p: ESP RMT RX memory bank
UBaseType_t pollTaskPrio_p: The link scan process priority (0-24
Higher is more)
UBaseType_t pollTaskCore_p: The link scan process core (0-1)
uint8_t scanInterval_p: The link scan period (1-255 ms)
Returns:
sateliteLink* The object handle.
~sateliteLink(void)Description:
Destroys a previously created sateliteLink object. The sateliteLink
shall be disabled before calling the destructor.
Parameters:
-
Returns:
-
satErr_t enableSatLink(void)Description:
Enables the sateliteLink object, which involves an auto discovery for
Satelites, creation of satelite objects and administrative enabling of
the sateliteLink. A call-back function should have been registered
through satLinkRegSatDiscoverCb in order to get the handle to newly
created Satelites.
Parameters:
-
Returns:
satErr_t return code
satErr_t disableSatLink(void)Description:
Disables the sateliteLink. This requires that all Satelites belonging to
the Satelite links have been admiratively disabled. It also results in
that all satelite objects belonging to the link are deleted. When those
are deleted, the user will get a call-back previously registered through
satLinkRegSatDiscoverCb informing about the upcoming deletion of the
satellite object.
Parameters:
-
Returns:
satErr_t return code
void setErrTresh(uint16_t p_errThresHigh, uint16_t p_errThresLow)Description:
Sets the error threshold for the sateliteLink "ERRSEC" operational
state.
Parameters:
uint16_t p_errThresHigh: High threshold for going in to "ERRSEC"
operational state
uint16_t p_errThresLow: Low threshold for ceasing "ERRSEC"
operational state.
Returns:
-
void satLinkRegStateCb(satLinkStateCb_t satLinkStateCb_p)Description:
Registers a call-back which is called whenever the operational state
of the sateliteLink Object is changed. **The call-back must be kept
short in time and not call any blocking functions.
Parameters:
satLinkStateCb_t satLinkStateCb_p: The pointer to the call-back
function.
Returns:
-
Call-back prototype:
typedef void (*satLinkStateCb_t)(sateliteLink* sateliteLink_p, uint8_t LinkAddr_p,
satOpState_t satOpState_p);Callback parameters:
sateliteLink* sateliteLink_p: The sateliteLink object handle.
uint8_t LinkAddr_p: The sateliteLink address.
satOpState_t satOpState_p: The operational state of the sateliteLink.
void satLinkUnRegStateCb(void)Description:
Unregisters the state call-back.
Parameters:
-
Returns:
-
void satLinkRegSatDiscoverCb(satDiscoverCb_t satDiscoverCb_p)Description:
Registers a call-back informing about creation and deletion of
satelite objects. If exists_p in the call-back is set to true a satelite
object was created, if false - a satelite object was deleted. In case of
deletion, the user must not return the call-back until all references to
that object have been destroyed and no methods of that object is
exercised, after returning the call-back the satelite object will be
deleted.
Parameters:
satDiscoverCb_t satDiscoverCb_p: The call-back function pointer.
Returns:
-
Call-back prototype:
typedef void (*satDiscoverCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
bool exists_p);Call-back parameters:
satelite* satelite_p: Satelite object handle.
uint8_t LinkAddr_p: Link address
uint8_t SatAddr_p: Satelite address.
bool exists_p: If true, a satelite object has been created, if false a
satelite object is about to be deleted.
void satLinkUnRegSatDiscoverCb(void);Description:
Un register of a discovery call-back.
Parameters:
-
Returns:
-
uint8_t getAddress(void)Description:
Returns the address of the sateliteLink object.
Parameters:
-
Returns:
uint8_t: Satelite link address.
uint8_t getSatLinkNoOfSats(void)Description:
Returns the number of Satelites discovered on the link. The addresses
of those are contiguous and starts from 0 (the Satelite closestt to the
master's RX).
Parameters:
-
Returns:
uint8_t Number of Satelites discovered on the link.
void getSatStats(satPerformanceCounters_t* satStats_p, bool resetStats)Description:
Provides the performance counters for the sateliteLink object.
Parameters:
satPerformanceCounters_t satStats_p: A pointer to a performance
counter object.
bool resetStats: If true, the performance counters are reset.*
Returns:
-
void clearSatStats(void)Description:
Clears the PM counters for the sateliteLink object.
Parameters:
-
Returns:
-
satelite* getsatHandle(uint8_t satAddr_p)Description:
Returns the satelite object handle for a given Satelite address. If
the Satelite address does not exist NULL is returned.
Parameters:
uint8_t satAddr_p: Satelite address
Returns:
satelite Satelite handle.
satErr_t admBlock(void)Description:
Administratively disables (blocks) the sateliteLink, this requires
that all satelite objects belonging to this link also are
administratively blocked. In difference to satLinkDisable, this method
does not delete the related satellite objects.
Parameters:
-
Returns:
satErr_t Return code
satErr_t admDeBlock(void)Description:
Administratively enables (de-blocks) the sateliteLink. In difference to
satLinkEnable, this method does not perform any auto discovery, nor does
it create any satellite objects.
Parameters:
-
Returns:
satErr_t Return code
satAdmState_t getAdmState(void)Description:
Provides the administrative state of the sateliteLink.
Parameters:
-
Returns:
satAdmState_t Administrative state.
satOpState_t getOpState(void)Description:
Provides the operative state of the sateliteLink.
Parameters:
-
Returns:
satAdmState_t Administrative state.
satErr_t enableSat(void)Description:
Enables a satelite, I.e., administratively enables it. This requires
that the parent sateliteLink object is enabled.
Parameters:
-
Returns:
satErr_t Return code.
satErr_t disableSat(void)Description:
Disables a satelite, I.e., administratively disables it.
Parameters:
-
Returns:
satErr_t Return code.
void setErrTresh(uint16_t errThresHigh_p, uint16_t errThresLow_p)Description:
Sets the error threshold for the satelite "ERRSEC" operational
state.
Parameters:
uint16_t p_errThresHigh: High threshold for going in to "ERRSEC"
operational state
uint16_t p_errThresLow: Low threshold for ceasing "ERRSEC"
operational state.
Returns:
satErr_t Return code.
satErr_t setSatActMode(actMode_t actMode_p, uint8_t actIndex_p)Description:
Sets the actuator mode for a satelite:
0: SATMODE_LOW - logical low
1: SATMODE_HIGH - logical high
2: SATMODE_PWM1_25K - 1.25kHz PWM
3: SATMODE_PWM100 - 100 Hz PWM
4: SATMODE_PULSE - Single High pulse
5 SATMODE_PULSE_INV - Single Low pulse
Parameters:
actMode_t actMode_p: Actuator mode
uint8_t actIndex_p: Actuator index (0-3)
satErr_t setSatActVal(uint8_t actVal_p, uint8_t actIndex_p)Description:
Sets the actuator value for an actuator on a Satelite - [%] for PWM
mode, [ms] for pulse mode.
Parameters:
uint8_t actVal_p: Actuator value (0-255) [%]/[ms]
uint8_t actIndex_p: Actuator index (0-3)
Returns:
satErr_t Return code.
satErr_t setSenseFilter(uint16_t senseFilter_p, uint8_t senseIndex_p)Description:
Set the filter time for the sensors.
Parameters:
uint16_t senseFilter_p: Sensor filter time (1-255) [ms].
uint8_t senseIndex_p: Sensor index (0-7).
Returns:
satErr_t Return code.
void getSatStats(satPerformanceCounters_t\* satStats_p, bool resetStats)Description:
Provides the performance counters for the satelite object.
Parameters:
satPerformanceCounters_t* satStats_p: A pointer to a performance
counter object.
bool resetStats: If true, the performance counters are reset.
Returns:
-
void clearSatStats(void)Description:
Clears the PM counters for the satelite object.
Parameters:
-
Returns:
-
void satRegSenseCb(satSenseCb_t fn)Description:
Register sensor callback
Parameters:
satSenseCb_t fn: Pointer to call-back function.
Returns:
-
Call-back prototype:
typedef void (*satSenseCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
uint8_t senseAddr_p, bool senseVal_p)Call-back parameters:
satelite* satelite_p: Satelite handle.
uint8_t LinkAddr_p: Satelite link address.
uint8_t SatAddr_p: Satelite address.
uint8_t senseAddr_p: Sensor address/index.
bool senseVal_p: Sensor state.
void satUnRegSenseCb(void)Description:
Unregister sensor call-back.
Parameters:
-
Returns:
-
satErr_t satSelfTest(selfTestCb_t selfTestCb_p)Description:
Initiate a self-test of a Satelite. The result will be delivered
through the call-back provided as parameter.
Parameters:
selfTestCb_t selfTestCb_p: Pointer to result call-back.
Returns:
satErr_t Return code.
Call-back prototype:
typedef void (*selfTestCb_t)(satelite* satelite_p, uint8_t LinkAddr_p,
uint8_t SatAddr_p, satErr_t selftestErr_p)Call-back parameters:
satelite satelite_p: Satelite handle.
uint8_t LinkAddr_p: Satelite link address.
uint8_t SatAddr_p: Satelite address.
satErr_t selftestErr_p: Self-test result.
bool getSenseVal(uint8_t senseAddr)Description:
Returns a sensor value.
Parameters:
uint8_t senseAddr: Sensor address/index.
Returns:
bool Sensor value.
void satRegStateCb(satStateCb_t fn)Description:
Register a call-back for operational state updates.
Parameters:
satStateCb_t fn: Pointer to call-back function.
Call-back prototype:
typedef void (*satStateCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
satOpState_t satOpState);Call-back parameters:
satelite* satelite_p: satelite handle.
uint8_t LinkAddr_p: Link address.
uint8_t SatAddr_p: Satelite address.
satOpState_t satOpState: Operational state.
void satUnRegStateCb(void)Description:
Unregister operational state call-back.
Parameters:
-
Returns:
-
uint8_t getAddress(void)Description:
Returns the address of a Satelite
Parameters:
-
Returns:
uint8_t Satelite address.
satErr_t admBlock(void)Description:
Administratively disables (blocks) the satelite, this is method is
equivalent with satDisable.
Parameters:
-
Returns:
satErr_t Return code
satErr_t admDeBlock(void)Description:
Administratively enables (de-blocks) the satelite, this is method is
equivalent with satEnable. It requires that the parent sateliteLink is
administratively enabled.
Parameters:
-
Returns:
satErr_t Return code.
satAdmState_t getAdmState(void)Description:
Returns the administrative state of a satelite.
Parameters:
-
Returns:
satAdmState_t Administrative state.
satOpState_t getOpState(void)Description:
Returns the operational state of a satelite.
Parameters:
-
Returns:
satOpState_t Operational state.
satErr_t opStateToStr(satOpState_t opState_p, char* outputStr_p, uint8_t length_p)Description:
Provides a clear text return code string from a return code without string termination.
Parameters:
satOpState_t opState_p: Operational state input.
char* outputStr_p: String.
uint8_t length_p:\ String length.\
Returns:
satErr_t Return code.
satErr_t formatSatStat(char* reportBuffer_p, uint16_t buffSize_p, uint16_t* usedBuff_p,
uint16_t buffOffset_p, uint8_t linkAddr_p, uint8_t satAddr_p,
satAdmState_t admState_p, satOpState_t opState_p,
satPerformanceCounters_t* pmdata_p, uint16_t reportColumnItems,
uint16_t reportItemsMask, bool printHead)Description:
Provides formated performance counter table report string. The reportColumnItems decides what performance counter columns that should be included, while the reportItemsMask decides what of those counters that should be included. printhead defines if the table heading should be included.
Parameters:
char* reportBuffer_p: Output string buffer.
uint16_t buffSize_p: String buffer size.
uint16_t* usedBuff_p: How much of the buffer was used.
uint16_t buffOffset_p: Offset for filling in the buffer.
uint8_t linkAddr_p: Link address for the report.
uint8_t satAddr_p: Satelite address for the report.
satAdmState_t admState_p: Administrative state for the object being reported (sateliteLink or satelite).
satOpState_t opState_p: Operational state for the object being reported (sateliteLink or satelite).
satPerformanceCounters_t* pmdata_p: Performance data structure.
uint16_t reportColumnItems: What pm data columns to include - see the format directives below.
uint16_t reportItemsMask: What pm data to report on - see the format directives below.
bool printHead: If true, the table head is included.\
Returns:
satErr_t Return code.
Performance counter format directives
#define LINK_ADDR\
#define SAT_ADDR\
#define RX_SIZE_ERR\
#define RX_SYMB_ERR\
#define TIMING_VIOLATION_ERR\
#define TX_UNDERRUN_ERR\
#define RX_OVERRRUN_ERR\
#define RX_CRC_ERR\
#define REMOTE_CRC_ERR\
#define WATCHDG_ERR\
#define ADM_STATE\
#define OP_STATEExample
satLink->getSatStats(&satLinkStats, false);
formatSatStat(reportBuff, 2000, &buffPointer, buffPointer, satLink->getAddress(), 0, satLink->getAdmState(),
satLink->getOpState(), &satLinkStats,
LINK_ADDR|SAT_ADDR|RX_SIZE_ERR|RX_SYMB_ERR|TIMING_VIOLATION_ERR|RX_CRC_ERR|REMOTE_CRC_ERR|WATCHDG_ERR|ADM_STATE|OP_STATE,
LINK_ADDR|RX_SIZE_ERR|RX_SYMB_ERR|TIMING_VIOLATION_ERR|RX_CRC_ERR|REMOTE_CRC_ERR|WATCHDG_ERR|ADM_STATE|OP_STATE,
true);
for(uint8_t i = 0; i < noOfSat; i++){
if (!drain[i] & satelites[i] != NULL){
xSemaphoreGive(methodAccessCnt[i]);
satelites[i]->getSatStats(&satStats, false);
formatSatStat(reportBuff, 2000, &buffPointer, buffPointer, satLink->getAddress(), satelites[i]->getAddress(),
satelites[i]->getAdmState(), satelites[i]->getOpState(), &satStats,
LINK_ADDR|SAT_ADDR|RX_SIZE_ERR|RX_SYMB_ERR|TIMING_VIOLATION_ERR|RX_CRC_ERR|REMOTE_CRC_ERR|WATCHDG_ERR|ADM_STATE|OP_STATE,
LINK_ADDR|SAT_ADDR|RX_CRC_ERR|REMOTE_CRC_ERR|WATCHDG_ERR|ADM_STATE|OP_STATE,
false);
}
}
Serial.printf("%s",reportBuff);Results in:
LinkAddr: SatAddr: Sizeerr: Symbolerr: Timingerr: RxCRCerr: RmCRCerr: Wderr: AdmState: OpState: 0 - 0 0 0 0 0 0 ENABLE WORKING 0 0 - - - 0 0 0 ENABLE WORKING
Return code type definition:
typedef uint64_t satErr_t;
// The lower 8 bits defines the local return code produced by the Satelite library -- se below:
#define SAT_OK 0x00\
#define SAT_ERR_SYMBOL_ERR 0x01\
#define SAT_ERR_EXESSIVE_SATS_ERR 0x02\
#define SAT_ERR_GEN_SATLINK_ERR 0x03\
#define SAT_ERR_WRONG_STATE_ERR 0x04\
#define SAT_ERR_DEP_BLOCK_STATUS_ERR 0x05\
#define SAT_ERR_PARAM_ERR 0x06\
#define SAT_ERR_RMT_ERR 0x07\
#define SAT_ERR_EXESSIVE_SATS 0x08\
#define SAT_ERR_SCANTASK_ERR 0x09\
#define SAT_ERR_NOT_EXIST_ERR 0x0A\
#define SAT_ERR_BUFF_SMALL_ERR 0x0B\
#define SAT_ERR_BUSY_ERR 0x0C\
#define SAT_SELFTEST_SERVER_CRC_ERR 0x0D\
#define SAT_SELFTEST_CLIENT_CRC_ERR 0x0E\
#define SAT_SELFTEST_WD_ERR 0x0F
satErr_t\[63:8\] // Can from time to time provide return codes coming from other libraries called // by this library.Administrative state:
typedef uint8_t satAdmState_t;
#define SAT_ADM_ENABLE 0x00
#define SAT_ADM_DISABLEOperative state:
Operative states are built up with bitmaps so that several operational
states attributes can
uniquely be overlayed on top of each other, E.g. SAT_OP_DISABLE
|SAT_OP_CONTROLBOCK.
The opStateToStr helper function will provide an operational state clear
text string corresponding
to the current operational state of an object, no matter if it is of
class sateliteLink or satelite.
uint8_t satOpState_t;
#define SAT_OP_WORKING 0x0000
#define SAT_OP_INIT
#define SAT_OP_DISABLE
#define SAT_OP_CONTROLBOCK
#define SAT_OP_ERR_SEC
#define SAT_OP_FAIL#define SATMODE_LOW
#define SATMODE_HIGH
#define SATMODE_PWM1_25K
#define SATMODE_PWM100
#define SATMODE_PULSE
#define SATMODE_PULSE_INVstruct satPerformanceCounters_t {
uint32_t txUnderunErr; // Not implemented/not applicable
uint32_t txUnderunErrSec; // Not implemented/not applicable
uint32_t rxOverRunErr; // Not implemented/same as scanTimingViolationErr
uint32_t rxOverRunErrSec; // Not implemented/same as scanTimingViolationErrSec
uint32_t scanTimingViolationErr; // Only applicable for sateliteLink
uint16_t scanTimingViolationErrSec; // For internal library use only
uint32_t rxDataSizeErr; // Only applicable for sateliteLink
uint32_t rxDataSizeErrSec; // For internal library use only
uint32_t rxSymbolErr; // Only applicable for sateliteLink
uint32_t rxSymbolErrSec; // For internal library use only
uint32_t wdErr; // Applicable for both sateliteLink and satelite
uint32_t wdErrSec; // For internal library use only
uint32_t rxCrcErr; // Applicable for both sateliteLink and satelite
uint32_t rxCrcErrSec; // For internal library use only
uint32_t remoteCrcErr; // Applicable for both sateliteLink and satelite
uint32_t remoteCrcErrSec; // For internal library use only
uint32_t testRemoteCrcErr; // For internal library use only
uint32_t testRxCrcErr; // For internal library use only
uint32_t testWdErr; // For internal library use only
};typedef void (*satLinkStateCb_t)(sateliteLink* sateliteLink_p, uint8_t LinkAddr_p,
satOpState_t satOpState_p);
typedef void (*satStateCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
satOpState_t satOpState);
typedef void (*satSenseCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
uint8_t senseAddr_p, bool senseVal_p);\
typedef void (*satDiscoverCb_t)(satelite\* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
bool exists_p);
typedef void (*selfTestCb_t)(satelite* satelite_p, uint8_t LinkAddr_p, uint8_t SatAddr_p,
satErr_t selftestErr_p);