State machine and lock
What this example shows
Walking the receiver through its states: a hardware reset on the RESET pin, the BOOTLOADER state a hardware reset puts it in, RUN state, CONFIGURATION state, and back into BOOTLOADER on purpose by using the lock. At each step the script asks the receiver which state it is in and prints the answer, then releases the lock so the receiver returns to RUN state.
The example code
This is Examples/ADSBReceiver-stateMachineAndLock.py from the pinned module,
without the file's header comment. The script body is exactly as shipped. It
uses the RESET pin on IO21, which this board wires to the receiver, together
with the UART1 wiring on IO17 and IO18.
import time
from machine import UART
from ADSBReceiver import ADSBReceiver
uart = UART(1, baudrate=115200, rx=17, tx=18, rxbuf=4096)
adsb = ADSBReceiver(uart, reset_pin=21)
print("Hardware-resetting the module (RESET pin)...")
if adsb.hardwareReset():
# BOOTLOADER holds for ~3s at the fixed 115200bps, then the module
# auto-transitions to RUN (unless locked). Wait it out before talking to it.
time.sleep_ms(3200)
else:
print("No reset_pin configured - skipping hardware reset, module keeps running.")
print("RUN -> CONFIGURATION")
if not adsb.enterConfiguration():
print("Failed to enter CONFIGURATION state.")
else:
# Ask the module to confirm which state it is actually in.
ok, state = adsb.getConfigState()
if ok:
print("AT+CONFIG? = {}".format(state))
print("CONFIGURATION -> BOOTLOADER (this also sets AT+LOCK=1)")
if not adsb.rebootToBootloader():
print("Failed to reboot to BOOTLOADER state.")
else:
# BOOTLOADER state always runs at the fixed 115200bps.
time.sleep_ms(200)
# Confirm the module really is in BOOTLOADER now.
ok, inBootloader = adsb.isBootloader()
if ok:
print("AT+BOOT? = {}".format("1 (BOOTLOADER)" if inBootloader else "0 (CONFIGURATION)"))
# The lock should be set, since rebootToBootloader() sets it automatically.
ok, locked = adsb.getLock()
if ok:
print("AT+LOCK? = {}".format("1 (locked)" if locked else "0 (unlocked)"))
print("Releasing lock: module will fall through to RUN state")
adsb.setLock(False)
# Module leaves BOOTLOADER and enters RUN at its configured run baud (115200 by default).
time.sleep_ms(200)
print("Done. Module should now be broadcasting in RUN state again.")
while True:
adsb.poll()
Save it to a file on your computer, then run it on the board with
mpremote run <file.py>, putting your file's name in place of <file.py>. It
needs the module installed as shown on the
MicroPython Library page.
Expected result
The script runs its sequence once, which takes a few seconds because of the 3.2
second wait after the hardware reset, and then keeps polling. The lines appear in
this order: the reset message, RUN -> CONFIGURATION, the AT+CONFIG? = line,
CONFIGURATION -> BOOTLOADER (this also sets AT+LOCK=1), the AT+BOOT? = line,
the AT+LOCK? = line, Releasing lock: module will fall through to RUN state
and Done. Module should now be broadcasting in RUN state again. The three lines
that report a value come from the receiver itself. The module's own description
of the first is 1 for CONFIGURATION at 115200 and 2 for CONFIGURATION at the set
baud rate.
Hardware-resetting the module (RESET pin)...
RUN -> CONFIGURATION
AT+CONFIG? = 1
CONFIGURATION -> BOOTLOADER (this also sets AT+LOCK=1)
AT+BOOT? = 1 (BOOTLOADER)
AT+LOCK? = 1 (locked)
Releasing lock: module will fall through to RUN state
Done. Module should now be broadcasting in RUN state again.
Functions used
ADSBReceiver(uart, reset_pin=None)returns ADSBReceiverCreates the receiver object on a UART you have already opened. If you give a reset pin, the module makes it a high-impedance input, so the pin is only driven during hardwareReset().
ReturnsA receiver object ready for the other functions.
Parameters
| Type | Name | Description |
|---|---|---|
machine.UART | uart | An open UART connected to the receiver. Size its receive buffer when you create it, as the example does with rxbuf=4096: dense traffic can overflow the default buffer and corrupt lines. |
int or None | reset_pin | GPIO wired to the receiver's RESET pin. Optional, default None, which disables hardwareReset(). This board uses 21. |
hardwareReset(pulse_ms=20, active_low=True, resync_to_baud=115200)returns boolResets the receiver by pulling the RESET pin low for a moment, then releasing it back to a high-impedance input. The receiver restarts in BOOTLOADER state at a fixed 115200 baud for about 3 seconds, then moves to RUN state unless it is locked. Bytes left over from before the reset are discarded.
ReturnsFalse if you gave no reset_pin to the constructor, in which case nothing happens. True otherwise.
Parameters
| Type | Name | Description |
|---|---|---|
int | pulse_ms | How long to hold the receiver in reset, in milliseconds. Optional, default 20. |
bool | active_low | True if the receiver resets while RESET is driven low. Optional, default True. |
int or None | resync_to_baud | Also switch the UART to this baud rate, so the next command is not sent at a stale rate. Optional, default 115200. None leaves the UART as it is. |
enterConfiguration()returns boolMoves the receiver from RUN to CONFIGURATION state. It sends AT+CONFIG=1, switches the UART to 115200 (the receiver's fixed CONFIGURATION baud rate) and confirms the new state with AT+CONFIG?.
ReturnsTrue if the receiver reports being in CONFIGURATION state, False otherwise.
getConfigState()returns tuple(bool, int)Asks the receiver which state it is in (AT+CONFIG?).
Returns(True, state) on success, where state is 0 for RUN, 1 for CONFIGURATION at 115200 and 2 for CONFIGURATION at the set baud rate. (False, 0) otherwise.
rebootToBootloader()returns boolReboots the receiver into BOOTLOADER state (AT+REBOOT_BOOTLOADER). It also sets the lock, so the receiver stays in BOOTLOADER afterwards.
ReturnsTrue on success, False otherwise.
isBootloader()returns tuple(bool, bool)Asks the receiver whether it is in BOOTLOADER state (AT+BOOT?).
Returns(True, in_bootloader) on success, (False, False) otherwise.
getLock()returns tuple(bool, bool)Asks the receiver whether the lock is set (AT+LOCK?). While it is set, the receiver stays in BOOTLOADER state.
Returns(True, locked) on success, (False, False) otherwise.
setLock(locked)returns boolSets or clears the lock (AT+LOCK=1 or AT+LOCK=0). Clearing it lets the receiver leave BOOTLOADER state for RUN state.
ReturnsTrue on success, False otherwise.
Parameters
| Type | Name | Description |
|---|---|---|
bool | locked | True to set the lock, False to clear it. |
poll()returns NoneReads every byte that has arrived, parses the complete lines and calls the registered functions. It does not block, so call it on every pass of your loop.
ReturnsNothing.
Putting it together
Settings can only be written in CONFIGURATION state, so the script enters it before it asks for the state, lock and bootloader flag.
rebootToBootloader() sets the lock for you, which is why the script reads the
lock back and then clears it with setLock(False): without that the receiver
would stay in BOOTLOADER state and send no aircraft data.