Skip to main content

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.

ShellMicroPython
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 ADSBReceiver

Creates 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

TypeNameDescription
machine.UARTuartAn 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 Nonereset_pinGPIO 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 bool

Resets 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

TypeNameDescription
intpulse_msHow long to hold the receiver in reset, in milliseconds. Optional, default 20.
boolactive_lowTrue if the receiver resets while RESET is driven low. Optional, default True.
int or Noneresync_to_baudAlso 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 bool

Moves 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 bool

Reboots 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 bool

Sets 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

TypeNameDescription
boollockedTrue to set the lock, False to clear it.
poll()returns None

Reads 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.