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, a mip reinstall or deleting every file leaves alone. A full chip erase (esptool erase_flash, mcuctl firmware flash --erase) loses them, and so does forget. Elsewhere they go in aioble’s ble_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: state and on_change tell 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: object

aioble’s ble_secrets.json, the format bledev.hid used first.

class bledev.security.NVSStore(namespace='bledev')[source]

Bases: object

The keys in ESP32 NVS, outside the filesystem.

One blob, bonds, in namespace bledev: for each secret its type (1 byte), key length (1), key, value length (2, little-endian), value.

bledev.security.pack_secrets(secrets)[source]

The NVS blob for {(type, key): value}.

bledev.security.unpack_secrets(buf)[source]

{(type, key): value} from an NVS blob; a torn tail is dropped.

bledev.security.default_store()[source]

NVS on an ESP32, the file anywhere else.

bledev.security.use_store(store=None)[source]

Keep the keys in store (a NVSStore, a FileStore, or "nvs"/"file"; default default_store) and turn bonding on.

Safe to call again; the last store wins. Returns the store.

bledev.security.store()[source]

The store in use, or None before use_store.

bledev.security.bonds()[source]

How many peers this board holds keys for.

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), or None. 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. Returns callback.

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.

mode is one of MODES. show(passkey) is called with the six-digit number to display (passkey and numeric), and hide() once the link’s security settles; without show, the number goes on display (default: board_config.display_drv when the board has one) and to the console. confirm(number) answers numeric comparison with True or False, or returns None and calls answer later.

bledev.security.answer(conn_handle, accept)[source]

Answer a numeric comparison that confirm deferred.

bledev.security.random_passkey()[source]

Six random digits, as an int (000000-999999).

bledev.security.poll()[source]

Run work the IRQ couldn’t schedule. Cheap when there’s none.

bledev.security.find_display()[source]

board_config.display_drv, or None on a board without a display.

bledev.security.display_passkey(display=None)[source]

(show, hide): draw a passkey big in the middle of display, and clear it again. Also prints it to the console. Without a display, only prints.