def restart_micropython_interpreter(xbee: XBeeDevice) -> Error:
"""
Restarts the MicroPython interpreter.
This allows the latest version of main.py/main.mpy to run,
assuming of course that Python Startup (ATPS) is enabled.
Assumes the XBee is already in API Mode Without Escapes.
Originally we hoped to implement this using the ATPYD command. As of 2019-09-23,
the XBee3 Cellular User Guide recommends the command ATPYD to soft-reboot
the MicroPython subsystem. However, this command no longer works, and it appears the docs
are out of date. The comments at the bottom of JIRA XBPY-227 state, "we eliminated
ATPYC and ATPYD in favor of ATPYB and ATPYE for clarity", so it seems that ATPYE is now
the best command to use.
HOWEVER, we discovered experimentally (and confirmed through discussions with the XBee team)
that ATPYE command doesn't actually seem to re-run the main.mpy file.
So we submitted a JIRA to request a new AT Command to perform a soft-reboot
of the MicroPython subsystem: https://jira.digi.com/browse/XBPY-431
For now, our workaround is to issue the ATFR (Firmware/Force Reset) command,
after of course performing a clean shutdown (see the shutdown_cleanly() function)
to prevent the possibility of cell modem module corruption. Note that non-cellular
XBees do not need this clean shutdown, so shutdown_cleanly() amounts to a NOP.
The ATFR is inelegant but there's not much else that we can do.
References:
- This page from the XBee3 Cellular User Guide: https://www.digi.com/resources/documentation/Digidocs/90002258/#Reference/r_cmd_PY.htm
- This page from Digi MicroPython Programming Guide: https://www.digi.com/resources/documentation/digidocs/90002219/#tasks/t_erase_code.htm
- More information about soft reset can be found on the following pages in the Digi MicroPython Programming Guide:
- https://www.digi.com/resources/documentation/digidocs/90002219/#tasks/t_reset_repl.htm
- https://www.digi.com/resources/documentation/digidocs/90002219/#tasks/t_run_code_startup.htm
"""
log("%s: First perform a clean shutdown before we issue the firmware/force reset (FR) command..."
% func())
err = shutdown_cleanly(xbee)
if err:
log("%s: Unable to cleanly shut down the XBee. Details: %s. Proceeding with the FR command anyway."
% (func(), err))
log("%s: Now issuing the FR command..." % func())
try:
xbee.execute_command("FR")
except Exception as ex:
return Error("%s: XBee FR command failed. Reason: %s" % (func(), ex))
log("%s: XBee FR command succeeded." % func())
return Success
ECU | [35] - [49]
INV | [50] - [96]
POS | [97] -
'''
#XBee setup and config
print("connecting to Xbee device at")
print(COM_port)
device = XBeeDevice("/dev/ttyUSB0", baud_rate) #COM port and Baud rate
device.open() #Open connection with the Xbee
device.execute_command("AP", bytearray('\x01', 'utf8'))
device.set_parameter("BD", bytearray('\x07', 'utf8'))
print("Connected to the Xbee Successfully!")
#Add a callback for when the XBee receives data
def my_data_received_callback(xbee_message):
address = xbee_message.remote_device.get_64bit_addr()
data = xbee_message.data.decode('utf8')
#add a timestamp which will be appended to each of the files
time = str(datetime.datetime.now().time()).split('.')[0] + "." + str(
datetime.datetime.now().time()).split('.')[1][0:3]
#Split the data up using the ',' delimiter
message = data.split(",")
#Now save data into the files based on the ranges shown in the table above
def shutdown_cleanly(xbee: XBeeDevice) -> Error:
"""
Helper function to attempt to cleanly shut down the XBee.
Note that only XBee 3 Cellular devices require a clean shutdown; this function
behaves as a NOP for XBee 3 Zigbee/802.15.4/DigiMesh devices.
You should invoke this function prior to issuing the ATFR command or removing power to the XBee.
Otherwise, you risk corrupting/bricking the XBee's cell modem chip.
For more info, see the "Clean shutdown" page in the XBee3 Cellular User Guide:
https://www.digi.com/resources/documentation/Digidocs/90002258/#Reference/r_clean_shutdown.htm
This function assumes that the XBee is currently in API Mode Without Escapes.
The clean shutdown is performed by issuing the XBee 3 Cellular ATSD (Shutdown) command to the XBee module.
Note that on XBee 3 Zigbee and 802.15.4 devices, the ATSD command does something completely different
(SD = Scan Duration).
Note that ATSD command does NOT put the XBee 3 Cellular device to sleep. Rather, it simply
puts the XBee module (particularly its cell modem chip) into a state in which it is safe to power off.
The XBee will continue to respond to API Frames messages even after it is in this shutdown state.
Note that the XBee 3 Cellular ATSD command takes a long time to respond, usually somewhere between
6 and 12 seconds, but it could be longer, so give it a nice long timeout, say 30 seconds, since
that is what the user guide recommends for alternate airplane mode shutdown approach.
We don't retry the shutdown command in a loop because a failure is highly unlikely.
If the shutdown command fails, we report the error, but we don't do anything else--
chances are you're still going to turn off the power no matter what, but at least
we tried to shut down so gracefully.
If the XBee 3 Cellular ATSD fails, we do attempt an alternate, fallback shutdown approach.
Note that the shutdown command (ATSD) was not introduced until the August 2019 release of
the XBee3 Cellular firmware, so older versions of firmware will need to rely upon this
alternate approach.
One approach mentioned on the [Clean shutdown page of the User Guide](
https://www.digi.com/resources/documentation/Digidocs/90002258/#Reference/r_clean_shutdown.htm)
is to de-assert the DTR_n/SLEEP_REQUEST pin and wait until the SLEEP_STATUS pin goes low.
However, if your XBee carrier board hardware was not designed with this in mind, you won't
be able to monitor this. Instead, we just wait for a specific reasonable amount of time, say 30 seconds.
After all, this is a fallback shutdown approach, and this is better than nothing.
However, there is another, bigger issue with the DTR_n/SLEEP_REQUEST approach:
this pin might not be configured as a sleep request input! In other words, the XBee register "D8"
might instead have it configured as a general-purposes digital I/O pin, in which case strobing
this pin won't work. Since I don't want to make any assumptions about how the XBee is configured,
I'm going to avoid the pin-based approach.
So instead, we will use the third shutdown approach described in the User Guide:
send the ATAM (Airplane Mode) command to put the device into airplane mode. Then we wait
30 seconds as prescribed in the User Guide to give it plenty of time to shut down.
Note that the ATAM (Airplane Mode) command gets applied immediately;
no need to subsequently send ATAC (Apply Configuration) to apply the changes.
"""
proto = xbee.get_protocol()
if proto not in (XBeeProtocol.CELLULAR, XBeeProtocol.CELLULAR_NBIOT):
log("%s: Device is not an XBee 3 Cellular; no need for clean shutdown. Bypassing clean shutdown."
% func())
return Success
xbee_atsd_timeout_sec = 30
xbee_time_to_wait_in_airplane_mode_sec = 30
log("%s: Adjusting the xbee-python command timeout value..." % func())
try:
default_timeout_sec = xbee.get_sync_ops_timeout(
) # Store default value so that we can put it back.
xbee.set_sync_ops_timeout(
xbee_atsd_timeout_sec
) # ATSD takes longer than most commands so give it extra time.
except Exception as ex:
return Error(
"%s: Failed to adjust the xbee-python command timeout value. Reason: "
% (func(), ex))
log("%s: Attempting to cleanly shut down the XBee. Sending shutdown command (ATSD)..."
% func())
try:
xbee.execute_command("SD")
log("%s: XBee shutdown command (ATSD) succeeded. Now safe to remove power from the module."
% func())
return Success
except Exception as ex:
log("%s: XBee shutdown command (ATSD) failed. Reason: %s. Will attempt fallback approach."
% (func(), ex))
finally:
xbee.set_sync_ops_timeout(default_timeout_sec)
log("%s: Attempting fallback approach to cleanly shut down. Sending ATAM command and waiting for %s seconds."
% (func(), xbee_time_to_wait_in_airplane_mode_sec))
try:
xbee.set_parameter("AM", b"\x01")
except Exception as ex:
return Error("%s: XBee ATAM command failed. Reason: %s" % (func(), ex))
time.sleep(xbee_time_to_wait_in_airplane_mode_sec)
log("%s: Done waiting for XBee to enter airplane mode. You may now remove power from the module."
% func())
return Success
