Skip to content

Files

Latest commit

sebromeroactions-user
sebromero
and
actions-user
Update documentation
Feb 20, 2025
8b7de82 · Feb 20, 2025

History

History
1577 lines (1026 loc) · 37.5 KB

api.md

File metadata and controls

1577 lines (1026 loc) · 37.5 KB

Summary

map_value

def map_value(x: float | int, in_min: float | int, in_max: float | int,
              out_min: float | int, out_max: float | int) -> float | int

Maps a value from one range to another.

Arguments:

  • x - The value to map.
  • in_min - The minimum value of the input range.
  • in_max - The maximum value of the input range.
  • out_min - The minimum value of the output range.
  • out_max - The maximum value of the output range.

Returns:

The mapped value as a float or int depending on the input.

map_value_int

def map_value_int(x: float | int, in_min: float | int, in_max: float | int,
                  out_min: float | int, out_max: float | int) -> int

Maps a value from one range to another and returns an integer.

Arguments:

  • x - The value to map.
  • in_min - The minimum value of the input range.
  • in_max - The maximum value of the input range.
  • out_min - The minimum value of the output range.
  • out_max - The maximum value of the output range.

Returns:

The mapped value as an integer.

MovementValues

A named tuple to store the x, y, and z values of the movement sensors.

class ModulinoMovement

class ModulinoMovement(Modulino)

Class to interact with the movement sensor (IMU) of the Modulino Movement.

__init__

def __init__(i2c_bus=None, address: int | None = None) -> None

Initializes the Modulino Movement.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

accelerometer

@property
def accelerometer() -> MovementValues

Returns:

  • MovementValues - The acceleration values in the x, y, and z axes. These values can be accessed as .x, .y, and .z properties or by using the index operator for tuple unpacking.

gyro

@property
def gyro() -> MovementValues

Returns:

  • MovementValues - The gyroscope values in the x, y, and z axes. These values can be accessed as .x, .y, and .z properties or by using the index operator for tuple unpacking.

class Modulino

class Modulino()

Base class for all Modulino devices.

default_addresses

A list of default addresses that the modulino can have. This list needs to be overridden derived classes.

convert_default_addresses

Determines if the default addresses need to be converted from 8-bit to 7-bit. Addresses of modulinos without native I2C modules need to be converted. This class variable needs to be overridden in derived classes.

__init__

def __init__(i2c_bus: I2C = None, address: int = None, name: str = None)

Initializes the Modulino object with the given i2c bus and address. If the address is not provided, the device will try to auto discover it. If the address is provided, the device will check if it is connected to the bus. If the address is 8-bit, it will be converted to 7-bit. If no bus is provided, the default bus will be used if available.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The address of the device. If not provided, the device will try to auto discover it.
  • name str - The name of the device.

discover

def discover(default_addresses: list[int]) -> int | None

Tries to find the given modulino device in the device chain based on the pre-defined default addresses. The first address found will be returned. If the address has been changed to a custom one it won't be found with this function.

Returns:

int | None: The address of the device if found, None otherwise.

__bool__

def __bool__() -> bool

Boolean cast operator to determine if the given i2c device has a correct address and if the bus is defined. In case of auto discovery this also means that the device was found on the bus because otherwise the address would be None.

connected

@property
def connected() -> bool

Determines if the given modulino is connected to the i2c bus.

pin_strap_address

@property
def pin_strap_address() -> int | None

Returns the pin strap i2c address of the modulino. This address is set via resistors on the modulino board. Since all modulinos generally use the same firmware, the pinstrap address is needed to determine the type of the modulino at boot time, so it know what to do. At boot it checks the internal flash in case its address has been overridden by the user which would take precedence.

Returns:

int | None: The pin strap address of the modulino.

device_type

@property
def device_type() -> str | None

Returns the type of the modulino based on the pinstrap address as a string.

change_address

def change_address(new_address: int)

Sets the address of the i2c device to the given value. This is only supported on Modulinos that have a microcontroller.

enter_bootloader

def enter_bootloader()

Enters the I2C bootloader of the device. This is only supported on Modulinos that have a microcontroller.

Returns:

  • bool - True if the device entered bootloader mode, False otherwise.

read

def read(amount_of_bytes: int) -> bytes | None

Reads the given amount of bytes from the i2c device and returns the data. It skips the first byte which is the pinstrap address.

Returns:

bytes | None: The data read from the device.

write

def write(data_buffer: bytearray) -> bool

Writes the given buffer to the i2c device.

Arguments:

  • data_buffer bytearray - The data to be written to the device.

Returns:

  • bool - True if the data was written successfully, False otherwise.

has_default_address

@property
def has_default_address() -> bool

Determines if the given modulino has a default address or if a custom one was set.

available_devices

@staticmethod
def available_devices(bus: I2C = None) -> list[Modulino]

Finds all devices on the i2c bus and returns them as a list of Modulino objects.

Arguments:

  • bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.

Returns:

  • list - A list of Modulino objects.

reset_bus

@staticmethod
def reset_bus(i2c_bus: I2C) -> I2C

Resets the i2c bus. This is useful when the bus is in an unknown state. The modulinos that are equipped with a micro controller use DMA operations. If the host board does a reset during such operation it can make the bus get stuck.

Returns:

  • I2C - A new i2c bus object after resetting the bus.

class ModulinoDistance

class ModulinoDistance(Modulino)

Class to interact with the distance sensor of the Modulino Distance.

__init__

def __init__(i2c_bus=None, address: int | None = None) -> None

Initializes the Modulino Distance.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

distance

@property
def distance() -> int

Returns:

  • int - The distance in centimeters.

class ModulinoBuzzer

class ModulinoBuzzer(Modulino)

Class to play tones on the piezo element of the Modulino Buzzer. Predefined notes are available in the NOTES dictionary e.g. ModulinoBuzzer.NOTES["C4"]

NOTES

Dictionary with the notes and their corresponding frequencies. The supported notes are defined as follows:

  • FS3, G3, GS3, A3, AS3, B3
  • C4, CS4, D4, DS4, E4, F4, FS4, G4, GS4, A4, AS4, B4
  • C5, CS5, D5, DS5, E5, F5, FS5, G5, GS5, A5, AS5, B5
  • C6, CS6, D6, DS6, E6, F6, FS6, G6, GS6, A6, AS6, B6
  • C7, CS7, D7, DS7, E7, F7, FS7, G7, GS7, A7, AS7, B7
  • C8, CS8, D8, DS8
  • REST (Silence)

__init__

def __init__(i2c_bus=None, address=None)

Initializes the Modulino Buzzer.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

tone

def tone(frequency: int,
         lenght_ms: int = 0xFFFF,
         blocking: bool = False) -> None

Plays a tone with the given frequency and duration. If blocking is set to True, the function will wait until the tone is finished.

Arguments:

  • frequency - The frequency of the tone in Hz (freuqencies below 180 Hz are not supported)
  • lenght_ms - The duration of the tone in milliseconds. If omitted, the tone will play indefinitely
  • blocking - If set to True, the function will wait until the tone is finished

no_tone

def no_tone() -> None

Stops the current tone from playing.

class ModulinoColor

class ModulinoColor()

Class to represent an RGB color. It comes with predefined colors:

  • RED
  • GREEN
  • BLUE
  • YELLOW
  • CYAN
  • VIOLET
  • WHITE

They can be accessed e.g. as ModulinoColor.RED

__init__

def __init__(r: int, g: int, b: int)

Initializes the color with the given RGB values.

Arguments:

  • r int - The red value of the color.
  • g int - The green value of the color.
  • b int - The blue value of the color.

__int__

def __int__() -> int

Return the 32-bit integer representation of the color. Used bits: 8 to 15 for blue, 16 to 23 for green, 24 to 31 for red.

class ModulinoPixels

class ModulinoPixels(Modulino)

Class to interact with the LEDs of the Modulino Pixels.

__init__

def __init__(i2c_bus=None, address=None)

Initializes the Modulino Pixels.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

set_range_rgb

def set_range_rgb(index_from: int,
                  index_to: int,
                  r: int,
                  g: int,
                  b: int,
                  brightness: int = 100) -> 'ModulinoPixels'

Sets the color of the LEDs in the given range to the given RGB values.

Arguments:

  • index_from int - The starting index of the range.
  • index_to int - The ending index (inclusive) of the range.
  • r int - The red value of the color.
  • g int - The green value of the color.
  • b int - The blue value of the color.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_range_color

def set_range_color(index_from: int,
                    index_to: int,
                    color: ModulinoColor,
                    brightness: int = 100) -> 'ModulinoPixels'

Sets the color of the LEDs in the given range to the given color.

Arguments:

  • index_from int - The starting index of the range.
  • index_to int - The ending index (inclusive) of the range.
  • color ModulinoColor - The color of the LEDs.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_all_rgb

def set_all_rgb(r: int,
                g: int,
                b: int,
                brightness: int = 100) -> 'ModulinoPixels'

Sets the color of all the LEDs to the given RGB values.

Arguments:

  • r int - The red value of the color.
  • g int - The green value of the color.
  • b int - The blue value of the color.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_all_color

def set_all_color(color: ModulinoColor,
                  brightness: int = 100) -> 'ModulinoPixels'

Sets the color of all the LEDs to the given color.

Arguments:

  • color ModulinoColor - The color of the LEDs.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_color

def set_color(idx: int,
              rgb: ModulinoColor,
              brightness: int = 100) -> 'ModulinoPixels'

Sets the color of the given LED index to the given color.

Arguments:

  • idx int - The index of the LED (0..7).
  • rgb ModulinoColor - The color of the LED.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_rgb

def set_rgb(idx: int,
            r: int,
            g: int,
            b: int,
            brightness: int = 100) -> 'ModulinoPixels'

Set the color of the given LED index to the given RGB values.

Arguments:

  • idx int - The index of the LED (0..7).
  • r int - The red value of the color.
  • g int - The green value of the color.
  • b int - The blue value of the color.
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_brightness

def set_brightness(idx: int, brightness: int) -> 'ModulinoPixels'

Sets the brightness of the given LED index.

Arguments:

  • idx int - The index of the LED (0..7).
  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

set_all_brightness

def set_all_brightness(brightness: int) -> 'ModulinoPixels'

Sets the brightness of all the LEDs.

Arguments:

  • brightness int - The brightness of the LED. It should be a value between 0 and 100.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

clear

def clear(idx: int) -> 'ModulinoPixels'

Turns off the LED at the given index.

Arguments:

  • idx int - The index of the LED (0..7).

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

clear_range

def clear_range(start: int, end: int) -> 'ModulinoPixels'

Turns off the LEDs in the given range.

Arguments:

  • start int - The starting index of the range.
  • end int - The ending index (inclusive) of the range.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

clear_all

def clear_all() -> 'ModulinoPixels'

Turns all the LEDs off.

Returns:

  • ModulinoPixels - The object itself. Allows for daisy chaining of methods.

show

def show() -> None

Applies the changes to the LEDs. This function needs to be called after any changes to the LEDs. Otherwise, the changes will not be visible.

class ModulinoKnob

class ModulinoKnob(Modulino)

Class to interact with the rotary encoder of the Modulinio Knob.

__init__

def __init__(i2c_bus=None, address=None)

Initializes the Modulino Knob.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

reset

def reset() -> None

Resets the encoder value to 0.

update

def update() -> bool

Reads new data from the Modulino and calls the corresponding callbacks if the encoder value or pressed status has changed.

Returns:

  • bool - True if the encoder value or pressed status has changed.

range

@property
def range() -> tuple[int, int]

Returns the range of the encoder value.

range

@range.setter
def range(value: tuple[int, int]) -> None

Sets the range of the encoder value.

Arguments:

  • value tuple - A tuple with two integers representing the minimum and maximum values of the range.

on_rotate_clockwise

@property
def on_rotate_clockwise()

Returns the callback for the rotate clockwise event.

on_rotate_clockwise

@on_rotate_clockwise.setter
def on_rotate_clockwise(value) -> None

Sets the callback for the rotate clockwise event.

Arguments:

  • value function - The function to be called when the encoder is rotated clockwise.

on_rotate_counter_clockwise

@property
def on_rotate_counter_clockwise()

Returns the callback for the rotate counter clockwise event.

on_rotate_counter_clockwise

@on_rotate_counter_clockwise.setter
def on_rotate_counter_clockwise(value) -> None

Sets the callback for the rotate counter clockwise event.

Arguments:

  • value function - The function to be called when the encoder is rotated counter clockwise.

on_press

@property
def on_press()

Returns the callback for the press event.

on_press

@on_press.setter
def on_press(value) -> None

Sets the callback for the press event.

Arguments:

  • value function - The function to be called when the encoder is pressed.

on_release

@property
def on_release()

Returns the callback for the release event.

on_release

@on_release.setter
def on_release(value) -> None

Sets the callback for the release event.

Arguments:

  • value function - The function to be called when the encoder is released.

value

@property
def value() -> int

Returns the current value of the encoder.

value

@value.setter
def value(new_value: int) -> None

Sets the value of the encoder. This overrides the previous value.

Arguments:

  • new_value int - The new value of the encoder.

pressed

@property
def pressed() -> bool

Returns the pressed status of the encoder.

class ModulinoButtonsLED

class ModulinoButtonsLED()

Class to interact with the LEDs of the Modulino Buttons.

on

def on()

Turns the LED on.

off

def off()

Turns the LED off.

value

@property
def value()

Returns the value of the LED (1 for on, 0 for off).

value

@value.setter
def value(value)

Sets the value of the LED (1 for on, 0 for off). Calling this method will update the physical status of the LED immediately.

class ModulinoButtons

class ModulinoButtons(Modulino)

Class to interact with the buttons of the Modulino Buttons.

__init__

def __init__(i2c_bus=None, address=None)

Initializes the Modulino Buttons.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

led_a

@property
def led_a() -> ModulinoButtonsLED

Returns the LED A object of the module.

led_b

@property
def led_b() -> ModulinoButtonsLED

Returns the LED B object of the module.

led_c

@property
def led_c() -> ModulinoButtonsLED

Returns the LED C object of the module.

set_led_status

def set_led_status(a: bool, b: bool, c: bool) -> None

Turn on or off the button LEDs according to the given status.

Arguments:

  • a bool - The status of the LED A.
  • b bool - The status of the LED B.
  • c bool - The status of the LED C.

long_press_duration

@property
def long_press_duration() -> int

Returns the duration in milliseconds that the button must be pressed to trigger the long press event

long_press_duration

@long_press_duration.setter
def long_press_duration(value: int) -> None

Sets the duration in milliseconds that the button must be pressed to trigger the long press event

on_button_a_press

@property
def on_button_a_press()

Returns the callback for the press event of button A.

on_button_a_press

@on_button_a_press.setter
def on_button_a_press(value) -> None

Sets the callback for the press event of button A.

on_button_a_release

@property
def on_button_a_release()

Returns the callback for the release event of button A.

on_button_a_release

@on_button_a_release.setter
def on_button_a_release(value) -> None

Sets the callback for the release event of button A.

on_button_a_long_press

@property
def on_button_a_long_press()

Returns the callback for the long press event of button A.

on_button_a_long_press

@on_button_a_long_press.setter
def on_button_a_long_press(value) -> None

Sets the callback for the long press event of button A.

on_button_b_press

@property
def on_button_b_press()

Returns the callback for the press event of button B.

on_button_b_press

@on_button_b_press.setter
def on_button_b_press(value) -> None

Sets the callback for the press event of button B.

on_button_b_release

@property
def on_button_b_release()

Returns the callback for the release event of button B.

on_button_b_release

@on_button_b_release.setter
def on_button_b_release(value) -> None

Sets the callback for the release event of button B.

on_button_b_long_press

@property
def on_button_b_long_press()

Returns the callback for the long press event of button B.

on_button_b_long_press

@on_button_b_long_press.setter
def on_button_b_long_press(value) -> None

Sets the callback for the long press event of button B.

on_button_c_press

@property
def on_button_c_press()

Returns the callback for the press event of button C.

on_button_c_press

@on_button_c_press.setter
def on_button_c_press(value) -> None

Sets the callback for the press event of button C.

on_button_c_release

@property
def on_button_c_release()

Returns the callback for the release event of button C.

on_button_c_release

@on_button_c_release.setter
def on_button_c_release(value) -> None

Sets the callback for the release event of button C.

on_button_c_long_press

@property
def on_button_c_long_press()

Returns the callback for the long press event of button C.

on_button_c_long_press

@on_button_c_long_press.setter
def on_button_c_long_press(value) -> None

Sets the callback for the long press event of button C.

update

def update() -> bool

Update the button status and call the corresponding callbacks. Returns True if any of the buttons has changed its state.

Returns:

  • bool - True if any of the buttons has changed its state.

is_pressed

def is_pressed(index: int) -> bool

Returns True if the button at the given index is currently pressed.

Arguments:

  • index int - The index of the button. A = 0, B = 1, C = 2.

button_a_pressed

@property
def button_a_pressed() -> bool

Returns True if button A is currently pressed.

button_b_pressed

@property
def button_b_pressed() -> bool

Returns True if button B is currently pressed.

button_c_pressed

@property
def button_c_pressed() -> bool

Returns True if button C is currently pressed.

Measurement

A named tuple to store the temperature and relative humidity measurements.

class ModulinoThermo

class ModulinoThermo(Modulino)

Class to interact with the temperature and humidity sensor of the Modulino Thermo.

__init__

def __init__(i2c_bus: I2C = None, address: int = DEFAULT_ADDRESS) -> None

Initializes the Modulino Thermo.

Arguments:

  • i2c_bus I2C - The I2C bus to use. If not provided, the default I2C bus will be used.
  • address int - The I2C address of the module. If not provided, the default address will be used.

measurements

@property
def measurements() -> Measurement

Return Temperature and Relative Humidity or None if the data is stalled

relative_humidity

@property
def relative_humidity() -> float

The current relative humidity in % rH

temperature

@property
def temperature() -> float

The current temperature in Celsius