Controller Board Base Class

This base class defines the required controller board API. The API includes pretty much anything that the sensor code would need to get via MicroPython on the actual hardware.

class firmware.board_base.BoardBase

Bases: object

This class defines the required controller API.

The hardware runs via MicroPython, and this class enables different controller derived classes to run in MicroPython or CPython either way. Anything the sensing logic would expect to get from the controller, including network, terminal, and system attributes, is abstracted with this base class.

active(active: bool) → None

Sets the Wi-Fi system active mode.

Parameters:

active – The desired active mode, True or False

config(key: str) → str

Returns a single configuration variable for the given key

Parameters:

key – The configuration key name

connect(ssid: str, pw: str) → None

Attempts to connect to the specified Wi-Fi network.

Parameters:

• ssid – The Wi-Fi network ssid (name)

• pw – The Wi-Fi network password

Returns:

Nothing

create_watchdog(timeout_ms: int) → None

Creates a CPU watchdog. On actual hardware it will need to be fed regularly, or it will reset the device.

Parameters:

timeout_ms – The amount of time in ms to set for the watchdog.

Returns:

Nothing

developer_mode() → bool

Returns whether the board is in developer mode.

Returns:

True or False whether the board is in developer mode

ds18x20_convert_temp() → None

Asks all DS18x20 devices connected to the one-wire pin to refresh the latest temperature in their scratchpad.

Must be called before reading temperatures, and give at least 750 ms in between.

Returns:

Nothing

ds18x20_read_temp(rom: bytes) → float

Reads the temperature from the specific DS18x20 ROM scratchpad.

Parameters:

rom – The ROM for the sensor of interest, as bytes.

Returns:

The temperature, in degrees Celsius.

ds18x20_scan() → list[bytes]

Performs a scan of one-wire DS18x20 connected to a specific machine Pin, returning sensor IDs

Returns:

A list of ROMs connected to the device, each as a bytes variable.

feed_watchdog() → None

Feeds the CPU watchdog (if it exists), to reset the timer back to full.

Returns:

Nothing

get_ntp_timestamp() → int | None

Attempts to read the current Linux timestamp from an NTP server.

Returns:

Returns the Linux timestamp (seconds since epoch) if successful, otherwise returns None

http_get(url: str) → ResponseBase

Attempts to dispatch an HTTP GET request to the specified URL.

Parameters:

url – The url to request

Returns:

A Response object, including status code and response data.

http_put(url: str, headers: dict, json: dict) → ResponseBase

Attempts to dispatch an HTTP PUT request to the specified URL, with given headers and JSON payload.

Parameters:

• url – The url to request

• headers – Additional data, which could include branch name, data mime type, authentication, etc.

• json – A dict payload to submit with the PUT request

Returns:

A Response object, including status code and response data.

ifconfig() → tuple[str, str, str, str]

Returns ifconfig information

Returns:

A tuple of network configuration: (IP, Subnet, Gateway, DNS)

isconnected() → bool

Returns whether the Wi-Fi system is connected to a network.

Returns:

True or False if connected or not.

load_json(json_readable_bytes) → dict

Reads from the provided JSON bytes read-able object and provides a Python dict

Parameters:

json_readable_bytes – A read-able object of JSON content bytes, such as a file opened with ‘rb’

Returns:

A Python dict representing the JSON content

localtime(linux_time_seconds: int | None = None) → tuple

Converts the provided Linux time, or the converted time if passed in, into a tuple of timestamp values.

Parameters:

linux_time_seconds – Number of seconds since the Epoch; a Linux timestamp.

Returns:

A tuple timestamp, with (year, month, day, hour, minute, second, weekday, year-day)

print(message: str) → None

Prints the given message to the console provided by the controller implementation.

Parameters:

message – A string message to print.

Returns:

Nothing

rtc_datetime(timestamp: tuple[int, int, int, int, int, int, int, int]) → None

Attempts to set the Real Time Clock (RTC) to the specified timestamp.

Parameters:

timestamp – A timestamp of (year, month, day, weekday, hour, minute, second, microsecond)

Returns:

Nothing

run_forever() → bool

Returns whether this controller should actually run “forever”.

In some derived classes, such as unit tests, you don’t actually want the machine to run forever. This function allows each controller implementation to define their own behavior.

Returns:

True if this controller should run forever, False otherwise

scan() → list[tuple[bytes, bytes, int, int, int, int]]

Scans for Wi-Fi networks, returning a list of network instances.

Returns:

A list of network tuples, where each contains: (ssid, bssid, channel, RSSI, security, hidden)

sleep(seconds: float) → None

Sleeps the system for the specified amount of time.

Parameters:

seconds – The floating point number of seconds to sleep.

Returns:

Nothing

system_hang(seconds: int | None = None) → None

Provides a single place for causing the system to “hang” for either an amount of seconds, or forever.

There are some scenarios where the system may need to hang for a few seconds, such as if an error pops up, and you want to hold the sensor for 30 seconds then let the machine reboot. That way the message may be seen on the sensor. In that case, call this with a positive integer number of seconds. The machine will hang that long, feeding the watchdog as needed to ensure the machine does not reboot during this hang.

There are some scenarios where the system may need to hang forever, such as if the sensor initialization fails immediately upon boot. In that case, call this with no argument, or None. The machine will hang forever, feeding the watchdog as needed to ensure the machine does not reboot automatically.

Parameters:

seconds – Number of seconds to hang, or None to hang forever

Returns:

Nothing

ticks_diff(milliseconds_a: int, milliseconds_b: int) → int

Calculates the difference between two ticks, including ring arithmetic to try to handle wrap-around scenarios.

Parameters:

• milliseconds_a – Higher of the two values returned from ticks_ms

• milliseconds_b – Lower of the two values returned from ticks_ms

Returns:

Effectively just milliseconds_a - milliseconds_b but attempts to handle wrap-around scenarios.

ticks_ms() → int

Returns an increasing millisecond counter, used for checking durations, not absolute time. It may overflow.

Returns:

An integer timestamp, milliseconds since some arbitrary but fixed time.

class firmware.board_base.PinBase(pin_id: str | int, direction: int = 0, pull: int = 0)

Bases: object

This defines the required needs of a controller Pin; such as setting, reading, and toggling values.

off() → None

Sets the pin to an OFF state.

on() → None

Sets the pin to an ON state.

toggle() → None

Toggles the pin between ON and OFF states.

value() → int

Gets the current ON/OFF value of the Pin. :return: 1 if the Pin is ON, 0 otherwise

class firmware.board_base.ResponseBase

Bases: object

This defines the required needs of an HTTP response; from an actual hardware HTTP response, or a mock.

close() → None

HTTP response objects have a close method that we use, so any response mocks need to implement their own.

raw

HTTP response as raw bytes

status_code

HTTP status code, like 200 or 401

text

HTTP response as string text