Micropython Transmit and specifying API frame type

I want to use Micropython to establish connection to a Zigbee coordinator (SkyConnect in my case) and then specify some endpoints (NOT the default ones that XBee3 (XB3-24) provides under the latest Zigbee firmware (1012).
I see in the release notes that:

1007 - Digi XBee 3 Zigbee (July 12, 2019)

1. Transmissions with explicit addressing (like API frame type 0x11) can now be
   sent using `xbee.transmit()` in MicroPython. Refer to the
   [MicroPython Programming Guide](http://cms.digi.com/resources/documentation/digidocs/90002219/#reference/r_function_transmit.htm)
   for usage.

says that it is possible to specify the API frame type in the ‘transmit()’ function. I’ve looked at the referenced documentation section for the ‘transmit()’ function but there is nothing about the ‘frame type’ as a parameter.
I can see the cluster, profile and other options but nothing about the frame ID.
How do I specify the frame ID that I want?

You don’t set the Frame ID field. You set the Cluster ID and End points instead. That tells the radio to use the Explicit frame with the proper Cluster ID and End point.

Thank you for the information.
To be clear, the explicit addressing command frame has the following fields that are specified by ‘optional’ parameters in the ‘transmit()’ function:

  • source endpoint
  • destination endpoint
  • cluster ID
  • profile ID
  • broadcast radius
  • transmit options
    Are you saying that I MUST provide the first 3 ONLY to have the function generate a frameID of x011?
    What happens if I don’t provide a profile ID, especially if I am NOT talking to another XBee device?
    As there are both 16-bit and 64-bit destination addresses in that packet but only a single ‘destination’ address (that can be ether be specified as a 16-bit or 64-bit value, how is the one field generated with the other field value is given?
    The function documentation does not provide a default for the ‘transmit options’ (presumably as these change according to the firmware used) but does this mean that I must provide this parameter?
    Can I suggest that the documentation for this function be updated to be clear - especially when “magic” happens behind the scenes depending on the ‘optional’ parameters that are given.

Actually you probably want to provide the bulk of the values. At least the first 4 items. The others are not needed and the default values will be used.

That documentation link is out of date, but the transmit() documentation in the PDF manual seems fairly clear to me.

The transmit() MicroPython API is a method of sending the equivalent of a host sending a “Transmit Explicit” API frame over the serial port. If you exclude any of the parameters, MicroPython will use the default values given in the documentation.

The xbee.transmit() API might be easier to understand if you look at the typehints that we provide in the xbee-micropython repository: https://github.com/digidotcom/xbee-micropython/blob/master/typehints/common/xbee/__init__.pyi#L121

As Tom mentions above, you can specify parameters like cluster ID, endpoint, profile, etc. in the xbee.transmit(...) call just as you can with a 0x11 API frame.

Hopefully this helps: The 1007 release notes say “Transmissions with explicit addressing (like API frame type 0x11) …”. Maybe changing that to “(as can be done using API frame type 0x11)” would have been less confusing? Because the xbee.transmit call serves the same purpose as a 0x11 API frame; you don’t have to specify a 0x11 value on the call to make it “behave” like a 0x11 API frame.

1 Like

OK - I think I have understood this now. The fact that the only reference to the ‘explicit addressing’ frame that I could find was in the Change Log meant that I was possibly mis-interpreting the wording used.
It said that these packets “…can now be sent…” which to me implied that they could not be sent before. Hence my misunderstanding that the ‘transmit()’ function was creating a different frame ID than before and therefore to maintain backward compatibility the 0x11 frame was created only when using the optional parameters.
I see now that the 0x11 frame is always created by the ‘transmit()’ function.
However the wording used by @mvut above (1st reply) also seems to imply that if you don’t specify the cluster ID and end point then you don’t get the explicit frame. This also threw me off the line.
Thanks all.

It seems there might be some confusion in the documentation. The frame ID for specifying the API frame type typically isn’t a parameter you explicitly set when using xbee.transmit() in MicroPython. Instead, the frame ID is automatically generated by the XBee module. The XBee module assigns a unique frame ID to each transmitted frame to help with tracking and acknowledgment.

And be careful not to confuse the “frame type” parameter from the API frames sent/received serially, with the “frame ID” field present in many of those frames and used to match responses to requests. Neither of those fields applies to messages sent via MicroPython.

1 Like