OpenBAS Arduino Query protocol In version 2.70.0 this new protocol has been added on the following communication ports: USB COM1 COM2 In communication ports COM1 and COM2 it can be selected in the system configuration and communication ports dialog box, it can be either one to one (point to point) or networked, both ports can be selected simultaneously if needed. The USB port supports the following protocols: ASCII terminal Optomux Arduino Query In the USB the selection of the port is automatically done, when the NX controller is reset it defaults to the ASCII terminal mode, to switch to the Arduino Query mode, the tilde character (~) switches back and forth between those two protocols. The greater than character (>) sent as the first character of the line switches the protocol to Optomux. This can be seen on next page when opening any Windows or Linux terminal set up at 9,600 baud and connecting to the USB port of the NX.
A typical setup using Tera Terminal is shown in the image below: Tera Term can be downloaded at: http://download.cnet.com/tera-term/3000-2094_4-75766675.html Here can be seen once opening the terminal and setting it up, that pressing the tilde character (~) switches back and forth between ASCII terminal and Arduino Query protocols. In the screenshot above can be seen that once in Arduino Query mode, the following queries were issued, (the case is not important): STATUS If there are any of the eight alarms active they will be reported back, otherwise local time will be sent back. VERSION Returns current version and model of controller TIME Returns the current internal real time clock of the controller. Being the USB a native point to point connection, there is no need to connect or disconnect to the NX database, as it is using the COM1 and COM2 communication ports, especially if used in networked mode (more on this explained below).
When connecting by the USB port and being in Arduino Query mode there is no need to connect or disconnect from the database, but still if the queries are sent will be acknowledged: DISCONNECT CONNECT NAME Will de-attach the Arduino from the database Attaches the Arduino to the database Returns the name of the currently attached NX controller COM1 or COM2 in point to point connectivity When connecting an Arduino to the COM1 or COM2 ports, there are two ways to do it. The first one is to install an accessory board OpenBAS-ACC-TTL which replaces the factory default RS485 driver with a TTL driver, so that the TX and RX pins of any UART port of an Arduino can be connected directly as shown in the picture on next page. Keep in mind that the Arduino UNO only has one UART and is used for downloading sketches, so when used as a UART, first the sketch must be downloaded and when the sketch is running, the serial monitor can t be used simultaneously. It is better to use an Arduino board with multiple UART communication ports such as the DUE that besides UART pins TX0 and RX0 has three more UART s 1, 2 and 3. In the diagram shown on next page UART3 pins TX3 and RX3 are connected to COM2 port of the NX controller. Note that when the OpenBAS-ACC-TTL board is used, the d- terminal of the NX controller becomes its transmit pin TX, and the d+ terminal becomes the receive or RX pin. In standard UART one to one (or point to point) connections, the TX from one controller goes connected to the RXX of the other controller, and vice versa, so keep this in mind when doing wiring diagrams and connecting.
Typical connections of an Arduino UNO and Arduino DUE, to communication ports COM1 and COM2 of an NX controller using point to point connection. Connect TX pin of Arduino to RX pin of NX and RX pin of Arduino to TX pin of NX Remove Isolation jumper of COM1 and COM2 0V RX TX 0V RX TX Install ACC-TTL board in COM1 and COM2 Connect TX pin of Arduino to RX pin of NX and RX pin of Arduino to TX pin of NX Use any UART availabe in the Arduino DUE The advantage of doing a one to one connection is that the database is always available, but the disadvantage is the distance for TTL connections is only 1 meter. When more than one NX needs to be connected to an Arduino to create a network, or if the standard length of 4,000 feet (1,200 meters) wants to be overcome, a TTL to RS485 is available to do this. Also keep in mind that when more than one NX controller is connected in an RS485 network each one has to have a unique address (ID) so that the Arduino can connect with one database at a time and avoid conflicts. On next page, the typical parameters needed to connect with an Arduino using the Arduino Query protocol are shown for both COM1 and COM2.
Typical setup for conneting with an Arduino using Arduino Query protocol. Set Address if controller will be networked to a unique number for each controller in the network. Set Baud rate, stop bits and parity of all controllers on the network to the same value, (keep in mind that in any individual controller if COM1 and COM2 are connected to different networks, the settings of each network can be different). Protocol to Arduino Query. COM1 or COM2 in network connectivity Set jumper to RS485 RS232 -d +d ref NX Address 1 TTL RS485 -d +d ref NX Address 2 Use any UART availabe in the Arduino DUE TTL to RS232 / RS485 converter can be powered by 5V from Arduino -d +d ref To other nodes in RS485 network NX Address 3
When the Arduino query protocol in the USB is unused for more than three minutes, it reverts to ASCII terminal mode, and sends a USB keep alive signal to avoid the CDC driver for dropping the USB serial port, so any time the interface si unused and reverts should be switched back to Arduino protocol by sending the tilde (~) character as shown on the following screen. When used in a network, there are to queries where the address of the desired database is opened with the CONNECT_NWK query, where a number between 1 to 254 is sent after the query to connect to a specific controller, all other controllers on the network disconnect from the RS485 network for transmitting so that the addressed controller can reply back to the query. To disconnect from all databases issue the DISCONNECT_NWK query as shown below.
As can be seen on the screen on last page, communications on networked controllers should always start with a DISCONNECT_NWK, so all controllers on the network disconnect from the network and go into listen mode. Next using CONNECT_NWK 1, the controller with address1 is attached to the Arduino and it can start sending queries, in this case it sent the STATUS, NAME and VERSION queries and then finally deattached y sending the DISCONNECT_NWK query. Once connected (or attached to a database, the following queries can be issued: All of the data base objects can be queried one by one or in ranges, for example above the following queries were issued: Status of analog inputs 1 to 10 Status of binary inputs 1 to 10 Status of binary outputs 1 to 20, if a communication override is present an asterisk (*) will be shown, if a local override is present, a pound (#) will be shown. Status of analog outputs 1 to 10, if a communication override is present an asterisk(*) The number of decimals from zero to three can be selected by issuing the queries using: STATUS Defaults to three decimals STAT_0 No decimals are shown (shows override status for AO) STAT_1 One decimal is shown STAT_2 Two decimal are shown As can be seen on following page advanced queries can be also issued, to find out if the values are within any given range:
In the following example the following queries were issued: STAT_0 AI shows the status of analog inputs 1 to 8, and the query returns their current value with no decimals. STATUS AI 1 TO 10 > 500 AND <700 queries analog inputs 1 to 10 whose values are in the range 500 to 700, only analog input 3 is within that range and the query returns showing [3]664.806. Also the OR keyword can be used instead of AND can be used in the query. COMMAND BO 1 TO 20 = 1 commands with logic priority binary outputs 1 to 20, if an override is needed the COMM_OV can be issued, and to release communication overrides the COMM_AU query can be used instead. COMMAND ADF 1 to 20 = 123.45 writes that specific value to ADF registers 1 to 20, the STATUS query below shows ADF 18 to 200 to verify the write. The database objects that can be queried are: AI Analog inputs 1 to 40 BI Binary inputs 1 to 40 AO Analog outputs 1 to 10 BO Binary outputs 1 to 60 (41 to 60 are lighting groups 1 to 20) ADF Data float 32 bits 1 to 100 ADI Data integers 16 bits 1 to 100 ADB Data bytes 8 bits 1 to 100 RBIT Result bit registers 1 to 255 RFLT Result float registers 1 to 255 (41 to 255 only available with dual core or XP memory) TMR Timers 1 to 16 RMT Remote points 1 to 255 (51 to 255 only available with dual core or XP memory installed).
Also the SELECT query can be issued to select the data base objects that meet a certain criteria, for example: STATUS BO shows which binary outputs are active 1 to 8 by default, and STATUS BO 1 TO 20 show status of binary outputs 1 to 20, =VAL: *0,*0,*0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, SELECT BO 1 TO 20 = 1 selects and shows only the digital outputs (relays) that are ON, in the case below: =IDX: 4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20, SELECT AI 1 TO 40 > 1000 will select the indexes of the analog inputs whose value exceeds 100 which in the query are returned as: =IDX: 1,4,5,6,7,8, SLECT AO 1 to 10!= 0 will select the index of the analog outputs that are nor equal to cero, in the below case: =IDX: 1, Buffer size Transmit and receive buffer size on USB, COM1 and COM2 is 64 bytes each, so if any query exceeds this size, the query response will be truncated at this length and a plus character (+), will be appended at the end of the query, for example in the queries shown on next pages this can be seen. It is the responsibility to the program generating the queries to check for truncated queries and issue smaller queries to obtain all necessary information.
On this queries can be seen that when the query size exceeds the 64 byte limit the response is truncated. For STATUS and SELECT the limit of the queried data base elements is the size of the elements data base itself. For COMMAND queries, up to 20 data base objects can be commanded at once to a single value, thus in the above example can be seen that 20 ADF have been written the value zero: command adf 1 to 20 = 0 =OK =0 [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,]+ Even while the response was truncated after the 19 th element, the 20 values were written, this can be verified with the status command, where all values are shown without decimals: stat_0 adf 1 to 20 =VAL: 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, If decimals were requested, the response would be have been truncated as shown below: status adf 1 to 20 =VAL: 0.000,0.000,0.000,0.000,0.000,0.000,0.000,0.000,+
Creating Arduino sketches A typical program in the Arduino shows how to turn ON/OFF relays. The program first will CONNECT, then in sequence COMMAND (turn ON/OFF) relay 1, then do the same for relay 2 and finally simultaneously turn ON/OFF relays 3 to 8, at the end will DICONNECT. Turning on the serial monitor in the Arduino IDE shows the commands as they are sent. The whole sketch listing is shown below. void setup() { // Make sure the NX controller connected to has the ACC-TTL adapter installed instead of the // RS485 driver, also connect: // --> The RX pin 0 of the Arduino to terminal (-D) which is TX of the NX controller // --> The TX pin 1 of the Arduino to terminal (+D) which is RX of the NX controller // --> The GND pin of the Arduino to terminal(ref) of the NX controller // Note that optionally the TTL to RS485 converter can be used for multiple networked NX // controllers to the Arduino } // Set the serial port at 9600 baud in the Arduino, aslo make sure the NX controller has the // same baud rate and the Arduino Query protocol selected. Serial.begin( 9600 ); // continued on next page
// continued from next page void loop() { Serial.print( "CONNECT\n" ); delay( 100 ); // Disconnect to database // Toggle first relay Serial.print( "COMMAND BO 1 = 1\n" ); Serial.print( "COMMAND BO 1 = 0\n" ); // Toggle second relay Serial.print( "COMMAND BO 2 = 1\n" ); Serial.print( "COMMAND BO 2 = 0\n" ); // Toggle simultaneously relays 3 to 8 Serial.print( "COMMAND BO 3 to 8 = 1\n" ); Serial.print( "COMMAND BO 3 to 8 = 0\n" ); } Serial.print( "DISCONNECT\n" ); delay( 100 ); // Disconnect from database The following is a typical picture showing the Arduino and an NX controller using COM2 with the accessory board ACC-TTL to use the straight connection between the Arduino and the NX.
Here the installation of the ACC-TTL accessory board can be better seen, don[t forget to remove the isolation jumper of the corresponding communication port Also the wiring of the TX and RX pins of the Arduino UNO as well as the GND terminal is here shown.
This is the same program as the previous one, but now the responses are received and printed out in the serial monitor. void setup() { Serial.begin( 9600 ); } // Same as last time void loop() { String response = { "" }; // send a query and print the response Serial.flush(); Serial.print( "CONNECT\n" ); delay( 100 ); response = Serial.readString(); Serial.print( response ); delay( 100 ); response = Serial.readString(); Serial.print( "TIME\n" ); delay( 100 ); response = Serial.readString(); Serial.print( response ); delay( 100 ); // Print the CONNECT response in the serial monitor // Get whatever is responded by the NX from the last // Serial.print() to flush the buffer // Print the TIME response in the serial monitor Serial.print( "COMMAND BO 1 = 1\n" ); // Toggle relay #1 Serial.print( "COMMAND BO 1 = 0\n" ); // continued on next page
} // continued from next page Serial.print( "COMMAND BO 2 = 1\n" ); // Toggle relay #2 Serial.print( "COMMAND BO 2 = 0\n" ); Serial.print( "COMMAND BO 3 to 8 = 1\n" ); // Toggle relays 3 to 8 at once Serial.print( "COMMAND BO 3 to 8 = 0\n" ); Serial.print( "DISCONNECT\n" ); delay( 100 );
Query Reference of Arduino Query protocol The following section contains additional references and examples for creating the queries: //////////////////////////////////////////////////////////////////// // Arduino Query by rikmed The "OpenBAS Arduino Query Language" or OAQL for short, referred as such hereafter, is simple using plain text for communications, and a response is returned for a Query. To set up communication between an Arduino/Raspberry PI/Terminal (hereafter only referred as "Arduino") using this Query language will be depending on the communication port. Using COM1 or COM2 interface to an Arduino is possible by installing an ACC-TTL interface board instead of the standard RS485 interface. This way a one to pone connection can be created between one Arduino and one NX board, distance between the two of them is however limited to only three feet (1 meter). Due to the one to one connection method no addressing information is needed in the Query at all. Optionally a TTL-RS485 converter can be used to overcome this limitation, and if using addressing information in the Query several NX can be networked to a single Arduino communication port. The USB port supports the OAQL as a point to point only as it is by nature a one to one connection, using the CONNECT / DISCONNECT commands an attachment is made to the NX database Prior to sending queries, the USB should be placed into "Arduino Query" mode by sending the '~' character. Similarly sending a space ' ' places the USB port in ASCII mode and sending a '>' character places the USB port in Optomux/N2-open mode The Ethernet gateway will have its own implementation of the OAQL as its own database might differ from that of a standard NX/Dual core controller with its own expanded ETH3 database. The Query structure is as follows, it is case insensitive and always should start by attaching the Arduino to the NX controller using the CONNECT command: DISCONNECT Disconnect (or de-attaches) the Arduino any attached NX database (as this is broadcast all NX controllers on the network de-attach at once and revert to 1-1 mode) CONNECT Connects (or attaches) the Arduino to the NX database in a 1-1 fashion DISCONNECT_NWK Disconnect (or de-attaches) the Arduino from the network, (as this is broadcast all NX controllers on the network de-attach at once but stay in networked mode) CONNECT_NWK [Address: is a number between 1..254] Connects (or attaches) the Arduino to the NX database with the corresponding address, NX devices should be set with unique addresses in the RS485 network The first query should be always a DISCONNECT as if a previously CONNECT command is in effect, it will force the connection to start with a known state in 1-1.
Note that when issued on a NX networks, as all controllers will reply with =OK_DISCONNECT, garbage might be received. Once connected, the NX controllers will monitor communications, if no activity is detected for more than 10 minutes they will automatically revert to the disconnected state. If a connection is successful, the connected NX controller will reply with an acknowledge to the connect message with the following format: =OK CONNECT PORT [ADDRESS 1..254] Optionally the address will be reported back if a network connection was requested Once connected, the database can be queried using the following commands: -- QUERY-- -- NOTES -- NAME =NAME [Controller name] Controller (Database source) name -- QUERY-- -- NOTES -- VERSION =v.vv.v NX10 Returns version number and controller type If any query is not being able to be interpreted it will give an error message in the form of: =ERROR [Optional error code] -- QUERY-- -- NOTES -- TIME =OK hh:mm:ss wdy dd/mm/yyyy Will report back current time -- QUERY-- -- NOTES -- STATUS =OK hh:mm:ss wdy dd/mm/yyyy Will return OK of no alarms present and local time =ALM [0x00] Will return alarms present and show in flag bits 1 to 8 in hexadecimal format -- QUERY-- -- NOTES -- STAT_0... Will send current value (value) of selected DB STAT_1... STAT_2... STATUS... object with 0 decimal positions (integer) Will send current value (value) of selected DB object with 1 decimal positions. Will send current value (value) of selected DB object with 2 decimal positions Will send current value (value) of selected DB object with 3 decimal positions (DEFAULT)
-- QUERY-- -- NOTES -- STATUS AI [1..40] [-D0..3] STATUS AI [1..40] TO [1..40] Will send current value (value) of selected AI Will send current value (value) of selected AI s up to 40 can be queried at once STATUS AO [1..10] [-D0..3] Will send current value (value) of selected AO s STATUS AO [1..10] TO [1..10] Will send current value (value) of selected AO s up STATUS BI STATUS BO STATUS BI 1 STATUS BI 1 TO 40 STATUS BO 1 to 60 STATUS ADB 1 TO 100 STATUS ADI 1 TO 100 STATUS ADF 1 TO 100 STATUS RBIT 1 to 255 STATUS RFLT 1 to 255 STATUS RMT 1 to 255 STATUS TMR 1 to 16 to 10 can be queried at once Will send current status of BI-1..8 in a comma separated value CSV format Will send current status of BO-1..8 in a comma separated value CSV format Will send current status of one binary input Will send current status of one binary inputs, up to 40 binary inputs can be queried at once Will send current status of one binary output current status of one binary output, up to 60 binary outputs can be queried at once, values in this query will be 1 or 0 Will send current status (value) of the BYTE setpoint selected Will send current status (value) of the INT setpoint selected Will send current status (value) of the FLOAT setpoint selected Will send current status (value) of the RES_BIT selected Will send current status (value) of the RES_FLOAT selected Will send current status (value) of the REMOTE POINT selected selected =VAL: x,y,z... =VAL: x,y,z...,+ Will send current status (value) of the REMOTE POINT Returns current value or values of queried data Returns current value or values of queried data, buffer is full -- QUERY-- -- NOTES STATUS AI > 5 Will select any AI whose value is greter than 5 =VAL: [1]6.000,[2]1500.120, Any AI that meets the criteria will be returned The index of the AI will be returned between square Brackets followed by the value, each data base Object will be separated by comma. Note the =VAL: identifier at the beginning of the Response to identify the STATUS between the SELECT queries
-- QUERY-- -- NOTES -- SELECT AI > 5 Will select any AI (1 to 8 default) whose value > 5 =IDX: 1,2, Any AI that meets the criteria will be returned The index of the AI which meet the criteria will be Returned, each object will be separated by comma. Note the =IDX: identifier at the beginning of the Response to identify the SEELECT between the STATUS queries. -- QUERY-- -- NOTES -- SELECT AI 1 TO 40 > 5 Will select any AI between 1 and 40 whose value > 5 SELECT AI 1 TO 40 > 5 AND <= 10 Will select any AI between 1 and 40 whose value > 5 AND <= 10 =IDX: 1,2,3,4 Query returns AI s that meet the criteria, the database object queried can be any and not only limited to analog inputs =IDX: 1,2,3,4,5,6,7,8,9,10,11,+ Query returns AI s that meet the criteria, the database object queried can be any and not only limited to analog inputs, buffer is full is denoted with the plus (+) character at the end. SELECT BI == 1 Will select all binary outputs in the range 1 to 8 that are = 1 (ON) SELECT BO 1 TO 20 = 1 Will select all binary outputs in the range 1 to 20 that are = 1 (ON) IDX: 1,2,3,4, =IDX: 1,*2,#3,4,5,6,7,8,9,10,11,+ Query returns BO s that meet the criteria, the database object queried can be any and not only limited to binary outputs Query returns BO s that meet the criteria, the database object queried can be any and not only limited to binary outputs, buffer is full is denoted with the plus (+) character at the end. For analog outputs and binary outputs an asterisk (*) means the output is overridden by communications, and the pound character (#) denotes it has a high priority local override. The following comparison operators can be used, also they can be joined with the AND or OR logic operators to form compounded comparisons: > Greater than >= Greater or equal than < Less than <= Less or equal than = or == Treated as equal than or assignment indistinctively!= Not equal than
Priorities for writing to data base objects in NX controllers When commanding in a query a data base object, its priority level should be taken into account, higher priority commands will have precedence over low priority commands, the table below depicts the priority levels used for NX controllers. HIGHEST PRIORITY PRIORITY_UNDEFINED_OFF 0 // 0000-0000 PRIORITY = 0 (if no LOCAL/COMM override) PRIORITY_UNDEFINED_ON 1 // 0000-0001 PRIORITY = 1 (if no LOCAL/COMM override) PRIORITY_UNDEFINED_OFF 2 // 0000-0010 PRIORITY = 2 (if no LOCAL/COMM override) PRIORITY_UNDEFINED_ON 3 // 0000-0011 PRIORITY = 3 (if no LOCAL/COMM override) PRIORITY_OVR_LOCAL_OFF 4 // 0000-0100, Set LOCAL OVVERIDE BIT PRIORITY_OVR_LOCAL_ON 5 // 0000-0101, Set LOCAL OVVERIDE BIT PRIORITY_OVR_COMM_OFF 6 // 0000-0110, Set COMM OVERRIDE BIT PRIORITY_OVR_COMM_ON 7 // 0000-0111, Set COMM OVERRIDE BIT PRIORITY_LOGIC_OFF 8 // 0000-1000 PRIORITY = 0 (if no LOCAL/COMM override) PRIORITY_LOGIC_ON 9 // 0000-1001 PRIORITY = 1 (if no LOCAL/COMM override) PRIORITY_SCHEDULE_OFF 10 // 0000-1010 PRIORITY = 2 (if no LOCAL/COMM override) PRIORITY_SCHEDULE_ON 11 // 0000-1011 PRIORITY = 3 (if no LOCAL/COMM override) PRIORITY_COMM_OFF 12 // 0000-1100 PRIORITY = 4 (if no LOCAL/COMM override) PRIORITY_COMM_ON 13 // 0000-1101 PRIORITY = 5 (if no LOCAL/COMM override) PRIORITY_OPERATE_OFF 14 // 0000-1110 PRIORITY = 6 (if no LOCAL/COMM override) PRIORITY_OPERATE_ON 15 // 0000-1111 PRIORITY = 7 (if no LOCAL/COMM override) LOWEST PRIORITY The COMMAND query sends a priority 12/13, so any logic instruction or schedule will have higher precedence on them, the COMM_OV will send an override with priority 6/7 so will have higher priority. Note that only analog outputs and binary outputs have priority bits for overriding them through communications, all other data objects will only have priority levels 8 and above. COMM_AU returns previously overridden analog and binary outputs to their released or auto (previous) state. COMMAND can write from 1 and up to 20 database objects in a single query, the numbers below depict only the allowable ranges that can be addressed, but any COMMAND query with more than 20 data base objects addressed will fail. -- QUERY-- -- NOTES COMMAND AO 1 TO 10 = VALUE Commands analog outputs to the given value, range of Commanded value for analog outputs is 0-100 (%) Commanded value for ADF is +/-32767 COMMAND BO 1 to 60 = 1 or 0 COMM_OV BO 1 to 20 = 1 or 0 COMM_AU BO 1 to 20 Commands binary outputs to the given value, value Of command is 0 or 1 Overrides binary outputs to the given value, Value of override is 0 or 1 releases communication overrides for binary and analog outputs.
-- QUERY-- -- NOTES COMMAND ADB [1..100] = VALUE Commands BYTE setpoint to given value, range of commanded value is 0..255 COMMAND ADI [1..100] = VALUE Commands INT setpoint to given value, range of commanded value is 0..65535 COMMAND ADF [1..100] = VALUE Commands FLOAT setpoint to given value, range of commanded value is +/-32767 COMMAND RBIT [1..255] = 1 or 0 Commands RES_BIT register to given value, range of Commanded value is 1 or 0 COMMAND RFLT [1..255] = VALUE Commands RES_FLT register to given value, range of commanded value is +/-32767 COMMAND RMT [1..255] = VALUE Commands RES_FLT register to given value, range of commanded value is +/-32767 =OK =VALUE [1,2,3,4] =OK =VALUE [1,2,3,4,+] Command accepted plus index of commanded objects Command accepted plus data, more data is available but not able to fit in the 64 byte buffer size. Note however that all objects were commanded If any query is not being able to be interpreted it will give an error message in the form of: =ERROR [Optional error code]