ProXR Quick Start Guide

This tutorial will help you learn to use our Base Station graphical user interface to control ProXR USB Relay Controllers.  Base Station is the software we use to demonstrate the features of our devices.  Base Station works by identifying the controller.  This software will generate a list of compatible control panels and demonstrate each individual feature.  This tutorial will display the bytes of data required to control our entire line of USB Relay Controllers.  This makes integration into your own software effortless, regardless of language or platform.  NCD USB Relay Controllers will act as a virtual com port on your PC.  Simply open the port and send your data to begin controlling relays.  Download Base Station Software from //ncd.io/start. Base Station software is compatible with Windows 8 and Windows 10.  The latest Dot NET framework must be installed when working with older operating systems.

USB Relay Controllers: A Complete Tutorial

This guide covers all ProXR series controllers, we will primarily be focusing on using USB ProXR and ProXR Lite Series controllers for communications as this is the preferred technology for product discovery and initial testing.  Base Station software supports other interface technologies including Wireless, Ethernet, Wi-Fi, Bluetooth, and RS-232, the directions are largely the same for all of these technologies as all communication modules communicate to the ProXR controller using serial data.  USB Controllers mount as a Virtual COM port on your computer.  Most Windows PCs include the drivers necessary to talk to our controllers; however, a comprehensive list of supported drivers and operating systems are available at https://ftdichip.com/drivers/vcp-drivers/

Once the controller is plugged into the USB port of your computer, the USB LED should light on the USB interface module plugged into the controller.  If this light does not illuminate, your computer has not properly enumerated the USB driver (please see the link above install the latest drivers).

Communications to any NCD controller is as easy as sending bytes of data out the serial port or virtual COM port.  The default baud rate for all ProXR and ProXR Lite devices we manufacture is 115.2K Baud, 8 Data Bits, 1 Stop Bit, No Parity. NCD controllers expect to receive raw bytes of data for best possible speed. For this reason, common terminal programs should only be used in a way that supports raw data bytes rather than ASCII. The tables in this guide are shown in Hexadecimal values by default with an option to display commands in decimal values using a button above each table labeled “Show as Decimal”. All NCD ProXR class controllers are “Speak When Spoken To” devices.  Send a command and receive a response. The Hex values shown should be sent out the communications port (TX Portion of the table) and the controller will respond (RX Portion of the table).

API Commands

This guide demonstrates the use of API commands.  Every command begins with 0xAA (170 Decimal) as a header byte, followed by the number of bytes in the Payload (the actual command).  Next, the actual command payload bytes are sent, followed by the 8-bit checksum.  Every command in this guide follows this sequence of operations.  To learn more about the API structure, please see the API Codec Quick Start Guide.  Since NCD controllers are “Speak when Spoken To” devices, they will respond with a API formatted response (when appropriate), which also begins with 0xAA (170 Decimal).  The Payload is what is responsible for controller operations.  The Payload should ALWAYS be “Wrapped” with a NCD API structure as described in the API Codec Quick Start Guide.

Before You Get Started…

Power and Hardware Setup

Before exploring this guide, it is critical to provide appropriate power to NCD ProXR Series controllers and any associated expansions.  NCD ProXR controllers require a 12V DC regulated power supply.  A switching power supply should always be used to properly regulate power to NCD controllers.  Unregulated supplies such as wall-wart type transformers can fluctuate voltage significantly.  These types of power supplies are not suitable for use with NCD controllers.  Be sure to always use a computer grade switching power supply to power NCD devices and expansions.  Please allow up to 100mA per relay as part of your power budget.  This may be excessive for some controllers as smaller relays may consume less than 50mA per relay channel; however, allowing for surge currents is considered best practice when possible.  Most ProXR series controllers consume less than 25mA standby current, but we recommend allowing for 100mA Standby power budget at 12VDC.  NCD controllers are shipped in a conductive static protection plastic bag.  Please remember, this bag is conductive, and placing the controller on top of this bag during initial testing can cause permanent damage to the controller.  Please place this controller on a non-conductive surface BEFORE powerup.

Fuses and Current Protection

NCD controllers are not fuse protected nor are they current protected.  Exceeding the current rating or short circuiting critical parts of the controller can cause damage to the controller or connected electronics.  We strongly recommend using NCD controllers along with current protection and/or fuse protection as necessary to prevent damage to the controller or connected devices.  Since every application is different, a power protection strategy that matches the installation application is strongly advised.

Application Limitations

Please remember that NCD devices are not suitable for use in applications that could endanger human life or property.  NCD devices are not certified for use in medical devices of any kind.  Relays have a limited lifespan and the eventual failure of a relay should never endanger people or property.  Please keep in mind that relays can fail in the “On” state whereby a relay cannot turn off.  It is also possible for relays to fail in the “Off” state whereby a relay cannot turn on.  Please be prepared for these types of failures.  If this is not acceptable, your application may require a custom manufactured certified solution.  Please remember that NCD devices, like all electronics, are subject to receiving Electromagnetic Interference.  Nearby lightning strikes, both direct or indirect, may cause failure or unintended operation.  Additionally, power disruptions, physical jarring, and other unforeseen events may also cause unintended operation.  While we have taken every reasonable precaution to prevent unintended operation, this is something that can never be 100% guaranteed.  Please plan for unintended operation as you implement the use of NCD controllers.

Expansion Controllers

Please note that it is critical for all expansion to be powered up along with the main controller simultaneously.  The main controller will attempt to turn all relays off upon power-up as a first order of operations.  This significantly reduces the chances of relay “glitching” on power-up.  Expansion controllers should NEVER be powered up after or independently of the main controller as the controller has no possible way of initializing a newly powered expansion.  All power and expansion ports must be connected prior to powerup and operation.  Expansion ports cannot be implemented or modified in any way while power is applied to the main controller.  Powering up any expansion controller AFTER the main controller is powered up will likely damage the main controller, expansion controller, or both.  The XR and UXP expansion ports actively send data to expansion controllers, even if they do not exist.  Sending data to an expansion that does not have power will likely cause serious damage.  In addition, expansion controllers that do not have a properly connected XR cable will cause unintended relay operation.  Powering a relay expansion independently of the main controller will also cause unintended relay operation.  It is absolutely critical to follow proper operation guidelines and to power-up the main controller along with all connected expansion controllers at the same time.

Base Station Quick Start Guide

The Base Station Quick Start Guide can also help you see commands in real-time as you click through the Base Station User-Interface.  This is hidden by default to help simplify the interface, be SURE to examine this short quick start guide to help get the most out of the user interface experience.

Relay Status Feedback

All NCD Relay Controllers will report the intended state of the relay as it is represented in the controller memory, which may not be the actual hardware state of the relay.  The hardware state of a relay cannot be monitored without current feedback from each relay, which is not supported in any of the existing generation of relay controllers.  In most applications, the memory state (or the intended relay state) is correct, but damaged relays, improperly powered expansion controllers, high-induction, or extreme EMI can cause a mismatch between the relay controller memory and actual on/off state of the relays.

Controlling Inductive Loads

NCD defines Inductive loads such as motors, solenoids, transformers, or any other device that causes motion or includes a magnetic coil of any kind.  These types of devices generate a magnetic field within the coil.  This magnetic field collapses when turned off.  The collapse of this magnetic field generates a voltage spike that flows back into the relay.  These inductive spikes can be severe and may need to be suppressed using capacitors.  Please review our guide on how to properly control inductive loads.

This section will demonstrate basic relay control commands, reading the status of relays, controlling all relays at once, including reversing and inverting relay status.  The video above demonstrates ProXR commands on a 4-Channel USB relay board.  This particular controllers is a ProXR Lite series, which includes 8 analog to digital inputs and USB interface module that may be replaced by a WiFi, Bluetooth, RS-232, Dropnet, Ethernet, Ethernet web page, or industrial wireless (Digi 802.15.4 or 900HP series) communications module.

Here, you will see the word “Bank”.  A bank is simply a group of 8 relays.  Bank 1 refers to the first group of 8 relays.  Bank 2 refers to the second group of 8 relays (for larger controllers).  ProXR controllers have firmware support for 32 Banks of relays, though it may not be possible to install 32 banks of relays for all installations.  Sometimes it is useful to send commands to a bank, so a Bank value is often included as part of the command.  Using a Bank value of 0 will apply a command to all banks of relays.

The tables below show sample commands found in this tutorial.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

The following table shows a single command used with different parameters.  The purpose of this command is to set the status of 8 relays simultaneously.  The 5th byte of this command indicates the binary pattern for relay control.  The 6th byte of this command applies this value to a single bank (Bank Value of 1-32) or all banks simultaneously (Bank Value of 0). Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Controlling individual relays refers to controlling relays by their designated numeric assignment rather than using the relay bank system we normally use.  These commands were included as an alternative method of controlling relays to help suit the preferences of a particular user.  Referring to relays by their numeric value may be easier for some users to comprehend, as relay 1 is the first relay on the board and relay 32 is the last relay on the board when working with a 32-channel relay controller.  This section also includes relay selector command, which can be used to select the activation of one particular relay, ensuring all other relays remain off.

The following commands make use of a RelayNumber parameter, which are always 16-bit values.  The RelayNumber is a the number of the relay you would like to control.  This RelayNumber variable is converted into LSB and MSB values, which is subsequently communicated to the controller.

RelayNumber = The Relay Number you would like to control.

LSB = ((RelayNumber) And 255)
MSB = (((RelayNumber) And 65280) / 255)

Since most users will be working with less than 256 relays, the following substitutions can be made to help simplify this process:

LSB = Relay Number (0 to 255)
MSB = 0

Should you need to speak to more than 256 relays, changing the MSB to 1 will only speak to relays above 256.  The following values will only talk to relays 256 to 511:

LSB = Relay Number (0 to 255)
MSB = 1 (This will send the LSB above to relays 256 through 512)

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note Bytes Received May be Different for Some Commands.

Toggle commands are used to toggle the state of a relay.  If a relay is off, the relay will activate when the toggle command is sent.  Similarly, if the toggle command is sent again, the relay turn off.

Toggle commands will require ProXR V3.9 firmware or later.

Relay grouping commands can help you save money, and in some cases, a lot of money.  Simulating large expensive relays with smaller low-cost relays is an excellent way to provide greater functionality at a much lower cost point.  Relay grouping is the process of controlling relays in groups rather than individual relays.  For instance, we do not offer 20-Amp DPDT relay.  Locating such a relay may be impossible or expensive, so instead, you can simulate a 20-Amp DPDT relay using two 20-Amp SPDT relays for a much more reasonable and accessible price.  Another common request we receive is a 10-Amp DPDT relay controller.  DPDT relays with a 10 Amp rating are more accessible, but still very costly.  Again, we can use a relay grouping command to simulate a 10-Amp DPDT relay using two 10-Amp SPDT relays.  You can really start saving money if you have needs for exotic relay configurations, such as 3PDT, 4PDT, or even 8PDT (if there is such a thing).

Relay grouping introduces a “Neighbor” variable to standard ProXR relay control commands.  The Neighbor parameter is used to define how many Neighboring relays you would like to apply to a relay control command.  Here’s an example:

Standard Command for Activating Relay 1:
Hex: AA 03 FE 6C 18
Decimal: 170 3 254 108 1 24

Standard Command for Activating Relay 1 + 1 Neighbor (2 SPDT Relays to Simulate a DPDT Relay):
Hex: AA 04 FE 6C 01 01 1A
Decimal: 170 4 254 108 1 1 26

The following relay grouping commands can be used to activate relays in groups, simulating DPDT, 3PDT, 4DPDT, and up to 8PDT relays using low-cost SPDT relays.  Note the Neighbor Parameter (N) has a maximum allowed value of 7.  Also note the (N) value cannot extend into the next bank.  For instance, Relay 1 has up to 7 neighbors, but Relay 8 has no neighbors because Relay number 9 is located in the next relay bank (Bank 2).  Here is a table of Neighbors allowed for each relay:

Here are a few examples that properly apply neighbors:

R= Relay
N = Neighbors
CK = Checksum (00-FF)

Flashing a Relays is the process of turning a relay on and off in the background while the controller processes other tasks.  Users are free to handle other relay control operations while relays are flashing.  Relay flashers make it easy to handle turn signal, road sign, and warning light applications with minimal integration time.  There are 16 Relay Flashers, allowing 16 relays to flash simultaneously.  Relay Flashers allow you to set the flash speed (S), which is applied to all Flashers (it is not possible to have each relay operating at a different flash rate).

Individual Flashers (F) may be turned On or Off (O) using the commands shown below.

F = Flasher (0 = All Flashers)
S = Speed of Flash (00-FF)
CK = Checksum (00-FF)

Relay Timers and Flashers are directly connected, meaning Relay Timer 1 is directly connected to Flasher 1.  Similarly, Timer 2 is connected to Flasher 2.  This makes it possible to flash a relay for a period of time using a pair of commands.  The following commands demonstrate Flash Timer features working together.

Start by turning on Flasher 1:

Next, Activate Timer 1:

When the timer expires, the relay flasher will be canceled.  Note that all 16 timers are connected to all 16 flashers in this same way.

This video demonstrates a 16-Channel relay board with a USB interface module installed.  By default, ProXR controllers automatically refresh relays.  When automatic relay refreshing is turned off, the relays will not change state when relay control commands are sent.  Instead, only the relay memory will change.  A separate relay refreshing command must be sent to make the controller update the status of the physical relays.  This allows users to send many relay control commands to the controller in any order, then refresh all relays simultaneously.

Commands Below are in Hex Format using API Mode. TX = Bytes Sent to the Controller RX = Bytes Received from the Controller.  Note: Bytes Received May be Different for Some Commands.

Scratchpad Memory is used to store 8 user defined bytes of data.  Scratchpad Memory can be used for anything, such as a location, serial number, or other type of identifier.  The values stored do not affect the operation of the controller, as this memory is specifically for user-defined purposes.  Please note, the controller MUST be set to Configuration mode to write to Scratchpad Memory.  The following commands will demonstrate reading and writing data from scratchpad memory.  Memory Location (L) and the return Value (V) are identified in the table below:

The following commands demonstrate how to write data to Scratchpad Memory.  Memory Location (L) has a possible value of 1 through 8 while Data (V) has a possible value of 0 to 255 (8-Bit).

Relay Timers are used to automatically control relays for applications that might require failsafe control.  For instance, controlling a relay using a standard relay control command may prove dangerous.  Instead, timers can be used to explicitly specify the duration of time a relay should be activated.  Using relay timer commands, users may tell a relay to turn on for 5 minutes.  Should the computer fail to communicate with the controller after 5 minutes, the relay will automatically shut off.  To extend this analogy, users may repeatedly tell a relay to turn on for 30 seconds.  The relay will stay on as long as the timer command is sent within 30 seconds.  If the computer stops sending the timer command, the relay will turn off after 30 seconds, acting as a failsafe switch to control loads that may be time sensitive.

ProXR controllers include 16 timers, each of which can have their own duration of time in Hours (HR) Minutes (MN) Seconds (SC).  Each Timer can control any Relay (R) using numeric ordering (the first relay is relay 0).  Two types of timers are supported, Duration and Pulse.  A Duration timer is a timer that activates a relay for a duration of time, then turns the relay off once the time has expired.  A pulse timer is a timer that pulses a relay only after the elapsed time has expired.  Pulse timers are useful for automatic gate control or garage door opening applications.  Duration timers are controlled using a (T) value of 50-65 as indicated in the table below.  Pulse timers are activated using a (T) value of 70-85.

Timers are simulated in firmware, and may not be suitable for applications that require precision accuracy.  Similarly, each timer shares the same time base, introducing a margin of error of 1 second when activating timers at random.  Perhaps the biggest technical question we receive regarding timers is a simple misunderstanding between the (T) and (R) columns in the table below.  All controllers are equipped with 16 timers, but different controllers are equipped with different numbers of physical relays.  A timer and a relay are not equal, but it may be helpful to use equal values as you learn.  For instance, always control the first relay with timer 0, the second relay with timer 1, etc.

For some users, a 32 channel relay controller may seem limited with only 16 timers.  However, any of the 16 timers may be applied to any of the 32 relays.  So as long as a timer is available (not active), it can be applied to any relay.  If your application requires more than 16 timers to run simultaneously, then a second controller would be required.

The following commands will set and activate a timer.

Relay Timers offer even deeper functionality, as they may also be paused or resumed at any time.  Similarly, relay timers may be set, but not activated until a later time.  Reading the status and remaining time of timers is also possible using the timer command set.

The following example commands demonstrate various timer features:

The following relay timer commands will configure the timer values only, but will NOT activate the timers.  Timer activation is handled by the “Relay Timers: Pause and Resume” section of this guide.

The commands below set the active status of all 16 timers.  Timers are either active or inactive, in other words, they are running (counting down), or they are paused (not counting down).  LSB and MSB are 16-bit binary values used to define the active state of each of the 16 timers.  When a specific timer is set active, all other timers are set as inactive.  When working with the above commands, make sure you always take into account that any bits not set will deactivate the associated timer, and may inadvertently deactivate any timers that may be running.  It’s also important to note the above commands will not cancel a timer, they will simply pause a timer.

The commands below demonstrate how to query a timer.  Using query commands, users may ask the controller the amount of time remaining for each timer.  Timers always count down in one second intervals, so each second, the received value will change for all active timers.  A timer query command will return 4 parameters: Remaining Hours (H), Minutes (M), Seconds (S), and the Relay (R) associated with the timer.

As mentioned earlier, relay timers are simulated in firmware, operating as a background process called by a timer interrupt.  ProXR controllers use an external system clock to maintain a 3% timing accuracy, not to be confused with a real time clock (RTC).  Since relay timers are derived from the system clock, it would stand to reason that relay timers maintain a 3% accuracy as well.  However, the CPU that powers ProXR controllers handles many interrupts on a priority basis, which can further deviate the accuracy to the timers.  ProXR relay timers are best suited for applications that do not require precise timing.  For instance, activating a porch light for 30 minutes, or closing a gate after 2 minutes, or ringing a school bell for 20 seconds.  These applications don’t really care if the timing is off by a few seconds.

Perhaps one of the most useful features of Relay Timers include the timer calibration function.  Timer calibration can be used to define the length of a second, as seen by the timer.  By lowering the timer calibration value, the timer can be accelerated.  Similarly, increasing the timer calibration value can greatly increase the length of a single second.  This feature is particularly useful if you need to control timing operations at a higher resolution.  Some customers have lowered these values to increase timing precision with great success.

Users may experiment with timer calibration in the “Timer Calibration” control panel.  This control panel allows you to experiment with activating 1, 8, or 16 timers simultaneously, testing short and long durations so you can see the actual effects of your settings over longer time periods.  Please note, since computers are interrupt driven, timing accuracy of the software is limited.

Be sure to write down your favorite calibration setting, as it will be necessary to use the “Device Configuration” control panel to store your timer values.

The “Relay Timer Samples” control panel demonstrates a few use case scenarios for timers.  This control panel does not introduce any new commands, and is intended for demonstration purposes only.

ProXR controllers allow you to read the on/off status one bank of relays or 32 banks of relays at a time.  Reading the current status of relays will incate the on/off status of all relays at any given time while reading the power-up status will indicate the on/off status of relays when power is first applied to the controller.

The last 4 commands in the sample return 35 bytes, beginning with a 170 header byte, followed by a value of 32 indicating the number of data bytes to expect, followed by 32 relay status bytes beginning with Bank 1, and concluding with a checksum value, which is the 8-bit sum of all previous bytes.

Select ProXR Series controllers are equipped with eight on-board analog to digital converters.  ADCs can be used to read many kinds of analog sensors as well as switches.  ADCs are available on all ProXR Lite series controllers as well as ProXR series that begin with ZAD in the part number.  This section of our tutorial will not apply to ProXR series with part numbers beginning with ZUXP.

ADCs are very sensitive to voltages, as their entire purpose is to convert a voltage from 0 to 5 volts into a value from 0 to 255 when using 8-Bit conversion mode (10-Bit mode converts voltages into values from 0 to 2047).  Analog inputs should never be left in a “floating” state.  In other words, they should be connected at all times to a voltage source or ground to keep the quiet.

ProXR controllers use eight 10K resistors to “pull” the inputs high (+5V) or low (Ground).  The integrated resistor network will ensure all inputs are always connected to ground or 5V using the “Pull Up/Down” jumper (as labeled on the circuit board).  Installing the jumper in the “Up” position will pull the analog inputs to 5V through the 10K resistor.  Likewise, installing this jumper in the “Down” position will pull the inputs to ground.  The default jumper setting is in the “Up” position.  This will allow the analog inputs to directly connect to switches, which is very useful if you need to manually control a relay from an analog input (See “AD8 Relay Activator / Event Generator” later in this guide).

The following commands demonstrate the 8-Bit AD8 command set.

Read All 8 Analog Inputs with 8-Bit Result per Channel:

The following command will return 16 bytes of data.  Data is arranged in numeric order (C1-C8) from channel 1 to channel 8.  Each channel is represented as a 10-Bit value (MSB and LSB).  The Checksum is represented in the CK column.

Converting MSB and LSB into an Integer:
The tables above demonstrate how 10-Bit data is communicated using 8-Bit values.  To convert the 8-Bit values into a usable integer, follow this simple formula:
Analog Value = (MSB x 256)  + LSB
Analog Value = (3 x 256) + 255
Analog Value = 1023

ProXR Lite and ZAD Series controllers include a Relay Activator and Event Generator configuration option.  This control panel is used to mondify memory, allowing users to control relays based on analog inputs.  This allows manual control of relays, which may be helpful in certain applications.  The event generator is very easy to use, as each analog input can be configured to perform a specific function.  By default, analog inputs don’t do anything.  However, users have many options to control relays when inputs change state.  Relay control is limited to the first 8 relays only for most functions, so users of larger relay controllers should plan manual activation events on the first 8 relays (Relay Bank 1 as marked on the circuit board).
To use this control panel users should set the Pull Jumper in the “Up” position.  
Be sure to click “Save Settings” anytime you make a change to this control panel.

Function 0: Do Nothing
Function 0 does nothing, this is the default setting.

Function 1-8: Momentary Relay Control
This function allows momentary control of relays based on input status.  When configured, the relay will activate when the analog input is connected to ground.

Function 9-16: Toggle Relay Control
This function allows users to toggle relays based on inputs.  When configured, the relay state will toggle each time there is a connection between input and ground.  Connect to a button for a “Push On/Push Off” relay control operation.

Function 17-24: Turn On Relay
Activate a Relay when inputs are configured using these function values.  When configured, the relay will activate when the input is connection to ground.  The relay will not be turned off using this command, this is a ON ONLY command.

Function 25-32: Turn Off Relay
Deactivate a Relay when inputs are configured using these function values.  When configured, the relay will deactivate when the input is connection to ground.  The relay will not be turned on using this command, this is a OFF ONLY command.

Function 33-40: Momentary Relay Flash
Flash a Relay when inputs are configured using these function values.  When configured, the relay will flash on and off while the input is connection to ground, the relay will stop flashing when the input is disconnected from ground.

Function 41-48: Toggle Relay Flash
Toggle a Flashing Relay when inputs are configured using these function values.  When configured, the relay will begin flashing once the input connects to ground.  Disconnect the input from ground, then reconnect the input to ground to stop the flashing operation.  Put simply, connect a button between the input and ground.  Push the button, the relay will flash.  Push the button again, the relay will stop flashing.

Function 49: Turn Off Relay Banks 1-4
Turn off relay banks 1-4 (32 relays) when inputs are configured using these function values.  When configured, all 32 relays will turn off each time there is a connection between input and ground.  This is a OFF ONLY command.

Function 50: Turn On Relay Banks 1-4
Turn on relay banks 1-4 (32 relays) when inputs are configured using these function values.  When configured, all 32 relays will turn on each time there is a connection between input and ground.  This is a ON ONLY command.

Function 51: Banks 1-4 Follow the Input Status (almost)
This is a relatively unusual command, users should experiment with it to see what it does.  Think of it as a bonus command, perhaps it will be useful for someone.

Send API Event:
ProXR AD8 Series controllers have the ability to send simple push notification data when a change is detected on the inputs.  When the drop down menu is configured to “Send Event on Port 1”, the controller will generate a packet of data reflecting the state of all inputs.  Simply monitor the data sent from the controller while connecting one or more inputs to ground to see the push notification data.

ProXR controllers (excluding ProXR Lite) include a XR Relay Expansion port.  This expansion port allows you to control more relays by adding expansion boards.  The XR port allows you to mix high-power and low-power relays together.  Easily add or mix signals relays, power relays, and solid state relays using the XR Expansion port.  ProXR controllers provide firmware support for control of 64 relay banks (512 relays).  However, it should be stated that due to EMI and cable distance limitations, it may not be possible to achieve a full 512 relay configuration.  As a general rule, the XR bus should extend no more than 3 feet from the main controller.  This length includes cabling AND the length of the relay expansion boards added together.  Anything beyond 3 feet should be considered experimental, and may prove unreliable for some applications.

Select ProXR series controllers that contain UXP in the part number include a UXP expansion port.  These controllers have different firmware that support compatible UXP expansion boards, allowing you to add Contact Closure Inputs, Potentiometer Outputs, and High-Resolution Analog to Digital Converters.  This section of our tutorial will demonstrate each of the expansion boards, and the commands associated with these expansions.  Please note that only one type of expansion is permitted on the UXP port.  For instance, if you choose Contact Closure inputs, then all expansions most be a contact closure input.  It is not possible to mix expansion types on the UXP port.  Also note that UXP controllers do not support any of the AD8 features mentioned above, including the AD8 activator features.

The UXP expansion port found on ProXR series controllers (equipped with a UXP port) support contact closure inputs.  These controllers allow you to connect buttons, switches, motion detectors, or any other type of contact closure input to your relay controller.  UXP series controllers are able to be read the contact closure inputs based on a polled protocol.  Polling is the process of asking the controller the current state of the contact closure inputs and receiving a reply.  Push notification is not supported for any UXP expansions.  Since inputs on this expansion will not accept voltages on the inputs, users should exercise caution when connecting external devices.

The following commands demonstrate how to read contact closure inputs from ProXR controllers equipped with UXP hardware and firmware.  A Bank (B) of 8 inputs is read for each request.  Each of 8 inputs is represented in standard byte format as part of the data returned (R) from the controller.  The Most Significant Bit of the returned data (R) represents Input 8 while the Least Significant Bit of the returned data (R) represents input 1.

Users may also request more than one bank at a time by specifying a start bank (S) and a count (C).  The start (S) bank is a value from 0 to 255 and the count (C) bank is a value of 0 to 31.  The Count (C) is added to the start bank, so the first example should be interpreted to mean: Read Contact Closure Inputs Starting (S) with Bank 0 and add a count (C) of 2 more banks for a total of 3 banks (24 total inputs).

The UXP expansion port found on ProXR series controllers (equipped with a UXP port) support up to 48 Channels of Analog to Digital Conversion with 12-Bit resolution.  These controllers allow you to read analog voltages from 0 to 5VDC, ideal for sensor monitoring applications.  UXP series controllers are able to be read ADC inputs based on a polled protocol.  Polling is the process of asking the controller the current voltage on any of the inputs and receiving a reply.  Push notification is not supported for any UXP expansions.  Users should exercise caution not to exceed 5VDC on any of the analog inputs to prevent permanent damage.

The ADC Inputs are divided into (I) Inputs and Devices (See Function Column).  Each devices has 16 available inputs (I), which will return (R) a standard 8-bit value based on the voltage present on the input at the time of reading.  Up to 3 devices are supported per UXP port for a total of 16 inputs per device, or 48 total available input channels.

The following commands demonstrate how to read individual analog inputs in 8-Bit mode from ProXR controllers equipped with UXP hardware and firmware:

CK = Checksum (00-FF)
I = Input
R = Return Value

The following commands will read all 16 channels at 8-Bit resolution:

The following samples read individual channels with 12-bit resolution.  These commands return 2 bytes, LSB and MSB.  The actual returned value can be computed using the following equation:
AD Value = (MSB x 256) + LSB

CK = Checksum (00-FF)
I = Input
LSB = Least Significant Byte of Return Value
MSB = Most Significant Byte of Return Value

The following commands read 16 channels at 12-Bit resolution, returning a total of 32 bytes:

The UXP expansion port found on ProXR series controllers (equipped with a UXP port) support the ability to control digital potentiometers.  Use the digital pot expansion boards for tuning of external analog circuits, audio control applications, or scientific control and simulation applications.  Digital potentiometers offer 8-bit resolution with the ability to control many channels individually or simultaneously.  Digital potentiometer outputs are available in 10K, 50K, and 100K ohm resistance.  Digital potentiometers are limited to working with analog circuits in the 0 to 5V range, and are current limited to 1ma per channel.  Exceeding the voltage or current on any of the potentiometers may result in permanent damage.

The following commands demonstrate how to control digital potentiometers from ProXR controllers equipped with UXP hardware and firmware using the Channel (C) and Value (V) parameters.  The channel value is used to identify which potentiometer you would like to control.  The value parameter controls the wiper of the potentiometer.  A value of 0 set the wiper all the way to the left.  A value of 128 moves the wiper to the center position.  A value of 255 move the wiper all the way to the right.  Note, as with most potentiometers, there are 3 contact points per potentiometer.

Users may want to set all potentiometer outputs simultaneously:

ProXR Controllers have two modes of operation: Configuration and Run
Run Mode is for daily use.  Your controller should remain in Run Mode most of the time, as this will prevent writing to the internal EEPROM memory, which could accidentally change important settings that could result in a complete loss of communications.
Configuration Mode unlocks important sections of memory, allowing settings to be altered.
There are two ways to change modes on ProXR series controllers: Software and Hardware
Changing modes in hardware is very easy, simply move the PGM/RUN jumper to the desired setting.
Changing modes in software requires you to send a few commands, along with a duration (D) of time (in seconds), indicating how long you would like the controller to remain in configuration mode.  You may set the duration (D) to 0 if you would like to cancel the timer and return to Run mode.

Hint: Should you ever loose communication with your controller, remove power, move the Jumper to Program Mode, power up the controller again.  Your ProXR controller will return to safe settings so you may recover your settings using our Base Station software.  

ProXR controllers are available in many varieties.  The following commands can help identify the ProXR controller and feature set available.

Each Device ID Byte above contains a very specific meaning, indicating available features for the controller.  It will be necessary to test each bit of every byte to obtain the complete feature set.  If you are not familiar with bitwise operations, examples are available in the Base Station Source Code at https://ncd.io/start

Device ID Byte 1

In the example Shown, the device returned &h63.

Convert the value &h63 to Binary to See Each Bit: %01100011 (8-Bit Binary Always Begins with Bit 7 and Ends with Bit 0)

If Bit 7 is Set, This Controller Supports Current Monitoring Command Set (External Hardware May Be Required)
If Bit 6 is Set, This Controller Supports AVA Security Protocols Command Set
If Bit 5 is Set, This Controller Supports the Scratchpad Memory Command Set
If Bit 4 is Set, This Controller Supports the AD1216 Analog to Digital Converter Command Set (External Hardware May Be Required)
If Bit 3 is Set, This Controller Supports the Programmable Potentiometer Command Set (External Hardware May Be Required)
If Bit 2 is Set, This Controller Supports Input Contact Closure SCAN Features (External Hardware May Be Required)
If Bit 1 is Set, This Controller Supports the AD8 Command Set Using Built-In Hardware
If Bit 0 is Set, This is a ProXR Class Controller

In the above example, Bits 6, 5, 1, and 0 are set, so the example controller supports the following features:

Bit 6 = 1: This Controller Supports AVA Security Protocols Command Set 
Bit 5 = 1: This Controller Supports the Scratchpad Memory Command Set
Bit 1 = 1: This Controller Supports the AD8 Command Set Using Built-In Hardware 
Bit 0 = 1: This is a ProXR Class Controller

Device ID Byte 2

In the example Shown, the device returned &h09.

Convert the value &h09 to Binary to See Each Bit: %00001001 (8-Bit Binary Always Begins with Bit 7 and Ends with Bit 0)

If Bit 7 is Set, This Controller Supports Fusion Decision Maker Logic
If Bit 6 is Set, This Controller Supports a Lifetime Counter
If Bit 5 is Set, This Controller Supports 8-Bit Digital I/O on Port 2
If Bit 4 is Set, This Controller Supports 8-Bit Digital I/O on Port 1
If Bit 3 is Set, This Controller Supports the AD8 Relay Activator Event Generator
If Bit 2 is Set, Reserved for Future Use
If Bit 1 is Set, This Controller Supports the Pulsar Light Dimmer Command Set
If Bit 0 is Set, This Controller Supports the E3C Command Set

In the above example, Bits 3 and 0 are set, so the example controller supports the following features:

Bit 3 = 1: This Controller Supports the AD8 Relay Activator Event Generator
Bit 0 = 1: This Controller Supports the E3C Command Set

Device ID Byte 3

In the example Shown, the device returned &h00, so none of the features below are supported.

If Bit 7 is Set, Fusion Class Controller 
If Bit 6 is Set, This Controller Supports Sonar Distance Measurement on Port 2
If Bit 5 is Set, This Controller Supports Sonar Distance Measurement on Port 1
If Bit 4 is Set, This Controller Supports the AD1216 Analog to Digital Converter on Port 2
If Bit 3 is Set, This Controller Supports the Programmable Potentiometer Command Set on Port 2
If Bit 2 is Set, This Controller Supports the Input Contact Closure SCAN Features on Port 2
If Bit 1 is Set, This Controller Supports the AD8 Command Set on Port 2
If Bit 0 is Set, This Controller Supports the Taralist Time Activated Relay Command Set

Device ID Byte 4

In the example Shown, the device returned &h80.

Convert the value &h80 to Binary to See Each Bit: %10000000 (8-Bit Binary Always Begins with Bit 7 and Ends with Bit 0)

If Bit 7 is Set, This Controller Supports the API Command Set
If Bit 6 is Set, This Controller Supports Dual Communication Ports
If Bit 5 is Set, This Controller Supports External Bus I2C Communications
If Bit 4 is Set, This Controller Supports Internal Bus I2C Communications
If Bit 3 is Set, Reserved for Future Use
If Bit 2 is Set, Reserved for Future Use
If Bit 1 is Set, Reserved for Future Use
If Bit 0 is Set, Reserved for Future Use

In the above example, Bits 7 is set, so the example controller supports API Communications.

Device ID Byte 5

In the example Shown, the device returned &h00, so none of the features below are supported.

If Bit 7 is Set, Reserved for Future Use
If Bit 6 is Set, Reserved for Future Use
If Bit 5 is Set, This Controller Supports MirW Control Functions
If Bit 4 is Set, This Controller Supports KFX Key Fob Configuration
If Bit 3 is Set, Reserved for Future Use
If Bit 2 is Set, Reserved for Future Use
If Bit 1 is Set, Reserved for Future Use
If Bit 0 is Set, This Controller Supports Push Notification