900HP-S3B Mesh API Frame Documents?

Michael_Head · April 11, 2019, 5:28pm

I’ve purchased an Industrial Relay Controller 4-Channel Board and purchased a 900HP-S3B Digi radio interface. I will use this combination in my existing Digi Mesh network. My network operates in non-escaped API mode. I expect to send API frames to the Relay Controller/Xbee which will then implement relay activity.

Please tell me where I can obtain documentation that describes control of the relays via the 900HP-S3B. I need to learn the format of frames to transmit to the Relay Controller/XBee.

Thanks!

jacob · April 11, 2019, 6:15pm

Hi Michael,

If you’re already familiar with the S3B packets then it should be fairly straightforward. If you’re not, we recommend reading Digi’s Digimesh documentation.

Do you have a model number or a series for the board you have?

What language were you planning on writing the software in?

Michael_Head · April 13, 2019, 1:47am

The boards in my network are XBP9B-DMST-002

I have these radios installed on my custom boards.

I write C-language software on my custom boards. This will create API frames for my radios.

I will use C-language software to create a Transmit Request Frame (0x10) which will carry the MAC address of the radio mounted on your relay board. Software will send this Frame to my radio. Magically by 900 MHz radio waves the frame will arrive at radio on your board, which will then implement relay control using hardware and software on your relay board.

A Transmit Request Frame carries a RF Data Field of variable length. I expect that this field will carry the instruction to your relay board to tell it which relay to turn on/off.

I seek a definition of what your board expects the RF Data Field to contain.

Or maybe the plan I’ve outlined above doesn’t fit your radio and board. Please supply your plan if so.

Mike

jacob · April 15, 2019, 2:21pm

Hi,

Yes that sounds feasible, I’m just not sure which relay controller you have. Different series of relay controllers may expect different commands.

The documentation that outlines the commands can be found under the resources tab of those individual products.

Michael_Head · April 15, 2019, 3:26pm

Hi Jacob,

I purchased Industrial Relay Controller 4-channel SPDT + UXP Expansion Port. Here is the URL

I purchased 900MHz XBee Pro. Here is the URL:

Here is the resources tab of the relay board I purchased:

There is a Communications section. I see Digi 802… document. This is NOT the Digi radio I purchased but is the closest entry in the section. I review this info and I find info concerning using your Base Station software with this radio and relay board.

I will NOT be using Base Station. I will send commands from my custom circuits using other Digi XBee radios. I need lower level information than what is supplied for using Base Station.

Please help me by directing me to a specific document.

I have purchased 1 board. It is for evaluation. If it works I will purchase additional boards at roughly 100/yearly rate.

Thanks!

jacob · April 15, 2019, 3:46pm

Hi Michael,

Got it. The documents you will need primarily are:

So once you’ve got the Digi S3B Digimesh frame API down you can start using that to send commands outlined in the ProXR Quick Start Guide (actually an in depth command set) and the API Codec Quick Start Guide (explains the API encoding wrappers).

Here’s a library you can use as a basis: https://github.com/ncd-io/Industrial-Relay-Control. Its written in Python, but its probably the easiest one we have to read.

Here’s another that has some digi handling as well: https://github.com/ncd-io/ncd-red-industrial for Node-Red/Node.js

Michael_Head · April 15, 2019, 4:10pm

Excellent! This will keep me busy for a while. Thanks

Mike

jacob · April 15, 2019, 4:13pm

No problem.

Honestly I would probably recommend a ZigMo or equivalent for a setup like this. The ZigMo is basically a USB to Wireless adapter. It would allow you to see exact byte values being sent by your devices. It will also allow you to configure your modules for encryption, transparent mode, etc.

Michael_Head · April 15, 2019, 4:21pm

Sorry, can’t use this suggestion.

I will integrate your board into a DigiMesh network of sensing. Sensors have Digi radios on them.

Your board will mount in customer’s electrical cabinet and be used to signal customer’s contactors which will then start and stop heavy equipment. Sensing will send instructions via DigiMesh to your boards thereby giving sensors the ability to control customer’s heavy equipment.

The application is similar to ventilation: Not enough air sensed - turn fans on until enough air is sensed.

Michael_Head · April 15, 2019, 6:20pm

Ok, just to be sure I see the forest from the trees…

My goal is to turn Relay 1 on in Bank 1. This is command

254, 108, 1

Which I get from * ProXR Quick Start Guide

I wrap this in NI API format according to definition in * API Codec Quick Start Guide to become

170, 3, 254, 108, 1, 24 (this is hex AA, 03, FE, 64, 00, 0F)

I take this package and further wrap it in Digi API format for their Transmit Request, according to Digi API Frame Document (below) and Digi Transmit Request Frame Document (below), specifying that address of the Digi radio on your board. NI board address for this example: 00 00 00 00 00 00 00 00

The final byte group is, according to Digi API Full Frame Example (XCTU output below) here is:

7E 00 14 10 01 00 00 00 00 00 00 00 00 FF FE 00 00 AA 03 FE 64 00 15 CD

Deconstructing this group makes it clearer:

7E - Digi packet identifier
00 14 - overall packet length
10 - TX Request Frame identifier
01 - TX Frame ID
00 00 00 00 00 00 00 00 - Address of remote NI relay board radio
FF FE - Digi reserved
00 - Digi broadcast radius
00 - Digi transmit options

AA - NI API packet identifier
03 - NI packet length
FE 64 00 - NI relay closure command
15 - NI checksum

CD - Digi Checksum

I send the above to my radio, it flows through the 900 MHz DigiMesh to your radio, and the relay closes?

Correct?

Digi%20API%20Frame%20Document !

Digi%20Transmit%20Request%20Frame%20Document !

!

jacob · April 15, 2019, 6:44pm

That looks accurate, but I’m not an expert on Digi’s API. I’ve only ever used their libraries which hid most of that.

Is that not working?

The command you’re sending in the frame generator is the 254 100 0 command which will deactivate the relay.

jacob · April 15, 2019, 7:13pm

I made this google sheet that outlines relay activation and de-activation in both hex and decimal formats: https://docs.google.com/spreadsheets/d/1I9AlbTaKfBiFkpAhvdIdc1Jm3KWqBjNV1XE7tQImP4Y/edit?usp=sharing

It may help in initial testing.

jacob · April 15, 2019, 9:10pm

I also just learned of a packet calculator we’re building for a new series called endNode. It will build you a correct packet for ProXR though: https://ncd.io/api-calculator/

Michael_Head · April 15, 2019, 10:44pm

OOPS, my mistake. Correct your documents show FE 64 00 turns relay 1 OFF, not ON as I wrote above.

Excellent references. I tried FE 64 00 with radio address 00 00 00 00 00 00 00 00 in the calculator and see the result

You: 7E 00 14 10 00 00 00 00 00 00 00 00 00 FF FE 00 40 AA 03 FE 64 00 0F 94
Me: 7E 00 14 10 01 00 00 00 00 00 00 00 00 FF FE 00 00 AA 03 FE 64 00 15 CD
Dif: xx xx xx xx aa xx xx xx xx xx xx xx xx xx xx xx xx bb xx xx xx xx xx xx cc

Difference aa is the Digi Frame ID. These are just frame tags so software can sort out returned frames if multiple frames are used.

Difference bb is are the Digi frame transmission options. You chose point-multipoint, I chose an invalid option.

Difference cc is just the different checksum owing to the different choices you and I made.

Simple! Thanks for making the communication via DigiMesh clear.

Michael_Head · April 17, 2019, 7:22pm

Hi Jacob,

I have follow-on question which is appropriate in this thread.

Our previous discussion involves sending your relay board a command to turn Relay 1 OFF. I learned where the basic command is, how to encode it into your API and then how to encode this into the Digi XBee radio API as a TX Request.

Now my goal is to get something back from your relay board. I would like to read an 8 bit result from ADC Input 1. Your documents give your API. I’ll repeat your document here:

I see I must send 254 150 after appropriate wrapping in your API and the Digi TX API. I’ve shown this wrapping method in example in the the previous communications.

Your document shows I can expect the board to respond with a single byte, (255 in your document but I guess any value 0 to 255 depending on ADC input), wrapped in your API format:

170 1 255 170

I expect this to arrive at my radio in a Digi API, which I can unwrap.

My concern now is how your relay board routes the return to me. I expect that your board will use DigiMesh and that it will use the Digi Transmit Request method of sending. In this case your relay board must know my radio’s address. How does the relay board obtain this address? How does it know where to send?

Mike

jacob · April 17, 2019, 8:50pm

Unfortunately the on-board processor doesn’t take this into account and will send the data to whatever the lower serial address is configured on the attached S3B module.

By default it will broadcast (0000ffff) so everything on the wireless network will get the response.

If you only ever need to access that board’s responses with just one “master” device then you can set the S3B module on the relay controller to use the master’s lower serial.

Also you’ll get the data in the serial buffer of the “master” device if that’s also part of the question.

jacob · April 17, 2019, 8:53pm

In fact each relay control command will send a response that should be read to make sure it went through successfully. We also recommend reading the response to make sure the device is actually ready for another command and not still processing the last command.

Michael_Head · April 18, 2019, 2:54pm

Hi Jacob,

The Digi Radio is a complex bit of hardware. In this reply I’ll attempt to translate your “whatever lower serial address is configured” into a definite feature in the Digi radio (S3B module).

Your relay board software could operate in transparent mode or in Digi API. I assume that it uses API from the discussion above concerning wrapping relay commands.

In API your relay board software has these choices for sending information out the Digi radio:

Which of these methods do you use?

Once I know the method I’ll dig deeper and ask questions on how you obtain the destination address in the context of the method.

jacob · April 18, 2019, 4:07pm

The relay board will operate in Transparent mode actually. The on-board processor sends a raw serial transmission without any S3B consideration out over serial to the S3B and the S3B wraps it up and transmits it.

The destination address lives on the S3B module itself and can be configured using X-CTU.

Michael_Head · April 18, 2019, 10:58pm

Hi Jacob,

I’ve done a little hunting with Digi Tech support. I’ll put what I’ve learned here for posterity.

Hi Tech Support,

I’m building a system of buoys to make measurements and relays to control equipment. These will communicate via DigiMesh using XBP9B-DMST-002 radios.

I’m evaluating a 3rd party as a hardware provider for a part of my buoy system. Have a look at

scroll mostly down to the bottom and you’ll see your radio. This board is a good fit in my system. I’ll use it to switch customer equipment on/off based on buoy sensing.

My plan is that the buoy will send commands by buoy Digi radio to relay board Digi radio. Relay will open/close.

But my buoy uses API mode. The relay uses Transparent mode. Bummer!

Details

The relay board generates a response for every command it receives.

The buoy will know the MAC address of the relay board radio.

I’m not sure how the relay board will know the MAC address of the buoy

Questions:

Will the relay board, DigiMesh, in transparent mode receive a TX Request (0x10) from the buoy?

If NOT, what can be done?

If SO:

Will the relay board response arrive back at the buoy?

What frame will this response arrive in?

===============================
Hello Mike,

AT / Transparent mode and API mode only refer to the way in which the module interacts with the device connected to the module’s UART.

There are many networks in use that have an API master and AT/Transparent slave nodes. This is probably the most common setup we see.

In your case, having a mixed AT/API network should be fine.

A 0x10 frame send from an API transmitter will be received by the intended AT or API receiver. Once in the air, the packets are basically encoded in the same way.

I hope that answers your question.

==================================

Q: Will the relay board, DigiMesh, in transparent mode receive a TX Request (0x10) from the buoy?

A: Yes. Correct.

Q: Will the relay board transparent mode response arrive back at the buoy?

A: As long as the DH/DL of the transmitter in transparent mode matches the SH/SL of the receiver, then yes.

Q: What frame will this response arrive in?

A:The response will arrive as a Receive Packet frame 0x90.