bledev.security
Pairing and bonding on a MicroPython board: the bond store, passkeys, link state.
You rarely call this yourself. bledev.repl.start(pairing=...) and
bledev.filetransfer.start(pairing=...) set it up, and a central’s
connection.pair() uses it. What it adds to aioble:
A bond store that survives a filesystem erase. On an ESP32 the keys go in NVS (namespace
bledev), which a reformat of the filesystem, amipreinstall or deleting every file leaves alone. A full chip erase (esptool erase_flash,mcuctl firmware flash --erase) loses them, and so doesforget. Elsewhere they go in aioble’sble_secrets.json.Passkeys. aioble leaves the passkey step unhandled. Here a board with a display shows a random six-digit passkey (
io=DISPLAY_ONLY) for the host to type in; numeric comparison shows a number both sides must confirm; and a board as central types in the passkey its peer shows.Link state per connection, from the stack’s encryption updates:
stateandon_changetell a server whether a link is encrypted, authenticated (passkey or numeric comparison) and bonded.
Only the board side lives here. A laptop’s pairing is the OS’s, through
bledev.bleak.
- bledev.security.IO_DISPLAY_ONLY = 0
IO capabilities, as
ble.config(io=...)takes them.
- bledev.security.MODES = ('justworks', 'passkey', 'numeric', 'auto')
The pairing modes a server takes.
"auto"is"passkey"on a board with a display and"justworks"without one.
- class bledev.security.FileStore(path='ble_secrets.json')[source]
Bases:
objectaioble’s
ble_secrets.json, the format bledev.hid used first.
- class bledev.security.NVSStore(namespace='bledev')[source]
Bases:
objectThe keys in ESP32 NVS, outside the filesystem.
One blob,
bonds, in namespacebledev: for each secret its type (1 byte), key length (1), key, value length (2, little-endian), value.
- bledev.security.unpack_secrets(buf)[source]
{(type, key): value}from an NVS blob; a torn tail is dropped.
- bledev.security.use_store(store=None)[source]
Keep the keys in
store(aNVSStore, aFileStore, or"nvs"/"file"; defaultdefault_store) and turn bonding on.Safe to call again; the last store wins. Returns the store.
- bledev.security.forget(address=None)[source]
Forget every bond, or the ones with
address(6 bytes, or"aa:bb:cc:dd:ee:ff"). A host that still holds its half must then be unpaired on the host before it can pair again.
- bledev.security.state(conn_handle)[source]
(encrypted, authenticated, bonded, key_size)for a connection.
- bledev.security.passkey_asked(conn_handle)[source]
time.ticks_ms()when the stack last asked about a passkey on this connection (shown, typed or compared), orNone. Cleared once the link’s security settles or it closes.
- bledev.security.on_change(callback)[source]
Call
callback(conn_handle, encrypted, authenticated, bonded, key_size)from the BLE IRQ whenever a link’s security changes. Returnscallback.
- bledev.security.expect_passkey(conn_handle, passkey)[source]
As central: the passkey to type in when this connection’s peer shows one (an int, a string of digits, or a callable returning either).
- bledev.security.configure(mode, *, show=None, hide=None, confirm=None, display=None)[source]
Set this board’s pairing as a peripheral. Returns the mode actually used.
modeis one ofMODES.show(passkey)is called with the six-digit number to display (passkey and numeric), andhide()once the link’s security settles; withoutshow, the number goes ondisplay(default:board_config.display_drvwhen the board has one) and to the console.confirm(number)answers numeric comparison with True or False, or returnsNoneand callsanswerlater.
- bledev.security.answer(conn_handle, accept)[source]
Answer a numeric comparison that
confirmdeferred.