API mode selection

[gaetancollaud]

I had some problems with this library. Depending on the payload of my packets, some were never transmitted... After looking in the source code and the datasheet (chapter 9 : API Operation) I found that this lib only use the escaped API Mode (API Enabled=0x2). And my devices are in the non-escaped mode (API Enabled=0x1).

So I had the possibility to change the API mode. The default mode is escaped, so nothing change for people that are already using this lib.

To change the mode to non-escaped just use this line in your sketch

xbee.setAPIMode(XBEE_API_MODE_OPERATION);

If you want to switch back to escaped mode :

xbee.setAPIMode(XBEE_API_MODE_OPERATION_ESCAPED);

[JChristensen]

I have wondered why non-escaped API mode (AP=1) even exists. What can the advantage be over escaped mode (AP=2)? I always use escaped mode; if there's any downside it would seem to be negligible, and I never have to worry that all the data I send will arrive OK.

[gaetancollaud]

There is no big advantage except a very small size gain. The thing is, when you flash your device with the last API firmware, the default mode is non-escaped (at least it was my case). And I think I'm not the only one.

This pull request won't change the default behaviour, it will just add the support of the non-escaped mode.

[JChristensen]

@gaetancollaud, that is my experience as well, the API firmware default is AP=1. But I'm usually changing at least a couple other parameters, so I just set AP=2 while I'm at it.

[gaetancollaud]

Anyway, are you for or against this pull request ? Do you have any comments ?

[JChristensen]

@gaetancollaud, I'd be OK with it as long as it doesn't add to processing overhead or to the code footprint. I'm a big advocate of lean and mean, especially with microcontrollers!

[gaetancollaud]

The only overhead is byte comparison when sending or receiving a packet. I use a byte for the apiMode variable. So the comparison is done very quickly (since the arduino is a 8bit controller). I let you be the juge, for me it's nothing.

I you use the non escaped mode, the part of code that escaped the data is skipped, so it's more effective to use in non escape mode (for the code execution point of wiew, but with all the disadvantages that the non-escaped mode come with).

In addition, as I said, I don't change the default operation mode. So if people were using your lib and update it, there is nothing to change.

[JChristensen]

Since it adds flexibility to the library at little or no cost, I'd agree it's a good addition. But I don't have real strong feelings either way, so I'll defer to Andrew, since it's his library. Like I said, I don't see much point in using AP=1 especially since Andrew has already done the heavy lifting for AP=2, so I'll no doubt stick with that. I'm willing to bear the modest processing overhead for added reliability.

Interestingly, I found this KB article on Digi's web site which says AP=2 is rarely used. It doesn't expand on why that might be the case (maybe because it's more work to code?) but it does give a little different spin on AP=1 than what I previously understood.

[matthijskooijman]

I guess that if you process data as big buffers, instead of sending data to the UART byte-by-byte, having to go over a buffer and add escapes is costly, having to move / copy all data in the buffer, so then non-escaped could give a speed gain.

If nothing in the serial path uses software flow control, using escaping isn't strictly required, which is probably why digi says AP=2 is uncommon? Also, escaping is typically hard for novice programmers, even though it is generally required for reliable communications. Apart from flow control, using AP=2 helps to resynchronize if the UART syncrhonization was lost (due to dropped bytes, or an error in a length byte, etc.), which I think is sufficient reason to use AP=2 already.

[JChristensen]

XBees are low-bandwidth devices. Buffers can't be too big, maximum RF payload size is 84 bytes for XBee ZB modules. My transmission intervals are typically 60 seconds or longer. Bottom line, I have to think that AP=2 adds little overhead in such scenarios but it might be interesting to check out. Flow control isn't the only reason for AP=2; I often send binary data, so there is the possibility that a byte could have a value of 0x7E, 0x7D, 0x11 or 0x13. Sending a 32-byte integer as four bytes and avoiding binary/ASCII conversions on both ends and sending up to 10 bytes probably more than compensates for the AP=2 overhead.

[matthijskooijman]

@JChristensen, I'm just saying that flow control is the only scenario in which you have to use AP=2. Sending binary data is perfectly possible with AP=1, as long as the packet sync is not lost. AP=2 helps making things more robust, but isn't required per se for binary packets.

[gaetancollaud]

dead PR I'm closing it