ArduinoProXR is an Arduino C++ library to communicate with Fusion Series relay boards (National Control Devices, LLC) using the ProXR Advanced command set. The author is not affiliated with National Control Devices, LLC.

Features:

• Compatible with any derived class of Stream
• No dynamic memory allocation
• Provides both a non-blocking interface for real-time applications as well as a blocking interface for simplicity

Prerequisites:

• Arduino IDE
• Git (optional)

1. Download this repository as a .zip file.
2. In the Arduino IDE, go to 'Sketch' > 'Include Library' > 'Add .ZIP Library'
3. Selected the downloaded .zip file and click 'Open'.

1. Find the location of your sketchbook folder in the Arduino IDE settings under 'Sketchbook location'. In the next steps, this path will be referred to as <sketchbook>.
2. Create a libraries folder within your sketchbook folder if it does not already exist.
3. Clone this repository to your libraries folder: in a command prompt, enter git clone https://github.com/iofarm/ArduinoProXR.git <sketchbook>/libraries/ArduinoProXR.

Several configuration options can be changed by editing ArduinoProXR_config.h.

Initialize RelayBoard using an instance of a class derived from Stream representing the hardware connection with the RelayBoard. For example, if your Arduino is connected to the Fusion controller via UART 2:

RelayBoard rb(Serial2);

Call RelayBoard::begin() after setting up the Stream instance; for example, in setup():

Serial2.begin(115200);
while (!Serial2);
rb.begin();

To send a command using the non-blocking interface, you must:

1. Queue the command using send() or one of its wrappers
2. Call loop() until the Arduino receives a reply from the relay board
3. Parse the reply within your callback function

ArduinoProXR uses callback functions matching the signature

void (*)(
  ProXRErr status, 
  void* context, 
  const uint8_t* response, 
  size_t len
)

where

• ProXRErr status is the error code
• void* context is a pointer set by the user
• const uint8_t* response is the decoded binary response from the relay board
• size_t len is the length of the response

To set the callback function and context pointer, use

setDefaultCallback(ProXRCallback callback, void* pointer);

Use send() to send a raw binary command, which takes the following arguments:

• const uint8_t* command - the binary command (not encoded)
• size_t len - the length of command
• callback (optional) - overrides the default callback function
• context (optional) - overrides the default context pointer

send() returns a ProXRErr error code indicating whether the command was successfuly queued - see Error codes for details.

A number of wrappers for send() are included for specific commands. These wrappers do not currently allow you to override the default callback and context. See Commands for details.

Your callback function can use one of the parser functions to parse and validate the response bytes. Each parser function takes the response bytes, response length, and reference(s) to variables to store the data in; and returns a ProXRErr return code indicating if there was a problem parsing the response. The struct BankStatus is used for responses that include a bank number and the status of relays in that bank.

Each wrapper function for a specific command also includes a blocking version indicated by the suffix _B. These functions will block until a response is received or until the command times out. They will also parse the responses, so some require references to variabels to store the response data in. See Commands for details.

The following wrappers for send() are available. Please see the ProXR Advanced command set documentation for details on using these commands.

* bank defaults to 0 (all banks)
** 1 byte will be written to status, unless bank == 0, in which case 32 bytes will be written
*** 32 bytes will be written to status

API functions return a ProXRErr enum. 0 indicates success, while positive values indicate an error: