nat20 Reference

Primary interface to Pixels dice.

async for scan in scan_for_dice():
    break

async with scan.connect() as die:
    die.blink_id(0x80)

class nat20.Pixel(sr: ScanResult)[source]

Class for a pixel die.

Do not construct directly, use scan_for_dice() to find the die you want and then use ScanResult.connect() to get an instance.

property address: str: The MAC address (UUID on macOS) of the die.

batt_level: int: Current battery level as a percent

batt_state: BatteryState: Current battery percent

async blink(*, color: int, count: int | ellipsis = 1, duration: float, fade: int = 0, led_mask: int = 255) → None[source]

Do an ad-hoc blink animation.

Parameters:

color – The color to flash, in 0xRRGGBB
count – The number of blinks to perform, or ... to go until cancelled
duration – The time of each on-off loop, in seconds
fade – The amount of time to spend fading, as a ‘percent’ (0-255) of a half-loop
led_mask – A bitmask of which LEDs to blink (1 means blink it, 0 means ignore it)

The blink will always have a 50% duty cycle.

Note

This only blocks until the die acknowledges the command, not until the animation is finished.

Note

Different animations can overlay each other and run in parallel.

async blink_id(brightness: int, loop: bool = False) → None[source]

Blinks rainbow, suitable for die identification.

Parameters:

brightness – 0-255, 0 is off, 255 is max brightness
loop – Whether to loop or just run once

Note

This only blocks until the die acknowledges the command, not until the animation is finished.

build_timestamp: datetime: Timestamp of when the firmware was built.

async calibrate_face(face: int) → None[source]

Calibrate a specific face.

The die must be resting on a flat, level surface with the noted face up.

async connect()[source]: Connect to die

connect_with_reconnect() → AsyncGenerator[Self, None][source]: Connect to the die and make an effort to automatically reconnect.

data_changed

set[str]) Any of the props changed, giving the set of which ones

Type:: Event
Type:: (cl

design_and_color: DesignAndColor: The aesthetic design of the die

async disconnect()[source]: Disconnect from die

disconnected

() We’ve been unexpectedly disconnected from the die.

Type:: Event

property face_count: int: The total number of faces

property flavor: DieFlavor: The kind of die this is, like D20 or Pipped D6

async get_battery_level() → BatteryLevel[source]: Request the current battery level.

async get_roll_state() → RollState[source]: Request the current roll state.

async get_rssi() → int[source]: Request the RSSI the die sees.

async get_temperature() → tuple[float, float][source]: Get the current temperatue of the die microcontroller and battery, in degrees Celsius.

got_battery_level

BatteryLevel) A new BatteryState has been sent.

Type:: Event
Type:: (bl

got_roll_state

RollState) A new RollState has been sent.

Type:: Event
Type:: (rs

property is_connected: bool: Are we currently connected to the die?

led_count: int: Number of LEDs

name: str: The textual name of the die.

notify_user

Callable[[OkCancel], None]) The die has something to tell the user.

Type:: Event
Type:: (cb

pixel_id: int: The factory-assigned die ID

roll_face: int: Current face that’s up, starting at 0. Validity depends on roll_state.

roll_state: RollState_State: Current roll state

async set_name(name: str) → None[source]: Change the name of the die.

async start_calibration() → None[source]

Start the calibration process.

Note that this method only _starts_ it. Interaction will occur via the notify_user event. The die will not function normally until the calibration is completed or times out.

async stop_all_animations() → None[source]: Stops any animations currently running, regardless of source.

to_batterylevel() → BatteryLevel[source]

Repackages the battery information.

Note that updated information hasn’t been received, the state can only be BatteryState.Ok or BatteryState.Charging.

to_rollstate() → RollState[source]: Repackages the rolling information.

async who_are_you() → IAmADie[source]: Perform a basic info query

class nat20.ScanBattState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

The charge state of the battery.

Charging = 1: The battery is charging

Ok = 0: The battery is discharging

as_batterystate() → BatteryState[source]

Repackage as a BatteryState.

Note that due to data fidelity, the state can only be BatteryState.Ok or BatteryState.Charging.

class nat20.ScanResult(_device: bleak.backends.device.BLEDevice, name: str, led_count: int, design_and_color: nat20.messages.DesignAndColor, roll_state: nat20.messages.RollState_State, roll_face: int, batt_state: nat20.ScanBattState, batt_level: int, pixel_id: int, build_timestamp: datetime.datetime)[source]

batt_level: int: The level of the battery, as a percent

batt_state: ScanBattState: The charge state of the battery

build_timestamp: datetime: The build date of the firmware

design_and_color: DesignAndColor: The aesthetic design of the die

property face_count: int: The total number of faces

property flavor: DieFlavor: The kind of die this is, like D20 or Pipped D6

hydrate() → Pixel[source]: Constructs a full Pixel class for this die.

led_count: int: The number of LEDs and faces

name: str: The name of the die

pixel_id: int: The unique ID of the die

roll_face: int: The current face (starting at 0)

roll_state: RollState_State: The motion of the die

to_batterylevel() → BatteryLevel[source]

Repackages the battery information.

Note that due to data fidelity, the state can only be BatteryState.Ok or BatteryState.Charging.

to_rollstate() → RollState[source]: Repackages the rolling information.

async nat20.scan_for_dice() → AsyncIterable[ScanResult][source]

Search for dice. Will scan forever as long as the iterator is live.

For timeouts, asyncio.timeout() might be helpful.