Skip to content

pysquared

Modules:

beacon

Classes:

Beacon

Beacon(logger: Logger, name: str, packet_manager: PacketManager, boot_time: float, *args: PowerMonitorProto | RadioProto | IMUProto | TemperatureSensorProto | Flag | Counter | Processor)

Methods:

  • avg_readings

    Get the average of the readings from a function

  • send

    Send the beacon

avg_readings

avg_readings(func: Callable[..., float | None], num_readings: int = 50) -> float | None

Get the average of the readings from a function

:param func: The function to call :param num_readings: The number of readings to take :return: The average of the readings :rtype: float | None

send

send() -> bool

Send the beacon

cdh

cdh Module

This module provides the CommandDataHandler class for managing and processing commands received by the satellite, including command parsing, execution, and radio communication handling.

Classes:

  • CommandDataHandler

    Handles command parsing, validation, and execution for the satellite.

CommandDataHandler

CommandDataHandler(logger: Logger, config: Config, packet_manager: PacketManager, send_delay: float = 0.2)

Handles command parsing, validation, and execution for the satellite.

Attributes:

  • logger (Logger) –

    Logger instance for logging events and errors.

  • _commands (dict[bytes, str]) –

    Mapping of command codes to handler method names.

  • _joke_reply (list[str]) –

    List of joke replies for the joke_reply command.

  • _super_secret_code (bytes) –

    Passcode required for command execution.

  • _repeat_code (bytes) –

    Passcode for repeating the last message.

  • radio_manager (RFM9xManager) –

    Radio manager for communication.

Methods:

change_radio_modulation

change_radio_modulation(args: list[str]) -> None

Change the radio modulation. :param modulation: The new radio modulation to set.

listen_for_commands

listen_for_commands(timeout: int) -> None

Listen for commands from the radio and handle them. :param timeout: Timeout in seconds for listening for commands.

reset

reset() -> None

Reset the hardware.

send_joke

send_joke() -> None

Send a random joke from the config.

config

Modules:

  • config

    Config module for PySquared.

  • radio

    Radio configuration module for PySquared.

config

Config module for PySquared.

This module provides the Config class, which encapsulates the configuration logic for the PySquared project. It loads, validates, and updates configuration values from a JSON file, and distributes these values across the application.

Classes:

  • Config

    Handles loading, validating, and updating configuration values, including radio settings.

Usage

Instantiate the Config class with the path to the configuration JSON file. Use the update_config method to update configuration values, either temporarily (RAM only) or permanently (persisted to file).

Example

config = Config("config.json") config.update_config("cubesat_name", "Cube1", temporary=False)

Config

Config(config_path: str)

Configuration handler for PySquared.

Loads configuration from a JSON file, validates values, and provides methods to update configuration settings. Supports both temporary (RAM-only) and permanent (file-persisted) updates. Delegates radio-related validation and updates to the RadioConfig class.

Attributes:

  • config_file (str) –

    Path to the configuration JSON file.

  • radio (RadioConfig) –

    Radio configuration handler.

  • cubesat_name (str) –

    Name of the cubesat.

  • sleep_duration (int) –

    Sleep duration in seconds.

  • detumble_enable_z (bool) –

    Enable detumbling on Z axis.

  • detumble_enable_x (bool) –

    Enable detumbling on X axis.

  • detumble_enable_y (bool) –

    Enable detumbling on Y axis.

  • jokes (list[str]) –

    List of jokes for the cubesat.

  • debug (bool) –

    Debug mode flag.

  • heating (bool) –

    Heating system enabled flag.

  • normal_temp (int) –

    Normal operating temperature.

  • normal_battery_temp (int) –

    Normal battery temperature.

  • normal_micro_temp (int) –

    Normal microcontroller temperature.

  • normal_charge_current (float) –

    Normal charge current.

  • normal_battery_voltage (float) –

    Normal battery voltage.

  • critical_battery_voltage (float) –

    Critical battery voltage.

  • reboot_time (int) –

    Time before reboot in seconds.

  • turbo_clock (bool) –

    Turbo clock enabled flag.

  • super_secret_code (str) –

    Secret code for special operations.

  • repeat_code (str) –

    Code for repeated operations.

  • longest_allowable_sleep_time (int) –

    Maximum allowable sleep time.

  • CONFIG_SCHEMA (dict) –

    Validation schema for configuration keys.

Methods:

  • validate

    Validates a configuration value against its schema.

  • _save_config

    Saves a configuration value to the JSON file.

  • update_config

    Updates a configuration value, either temporarily or permanently.

Parameters:

  • config_path
    (str) –

    Path to the configuration JSON file.

Raises:

  • FileNotFoundError

    If the configuration file does not exist.

  • JSONDecodeError

    If the configuration file is not valid JSON.

update_config
update_config(key: str, value, temporary: bool) -> None

Updates a configuration value, either temporarily (RAM only) or permanently (persisted to file).

Parameters:

  • key
    (str) –

    The configuration key to update.

  • value

    The new value to set.

  • temporary
    (bool) –

    If True, update only in RAM; if False, persist to file.

Raises:

  • TypeError

    If the value is not of the expected type.

  • ValueError

    If the value is out of the allowed range or length.

validate
validate(key: str, value) -> None

Validates a configuration value against its schema.

Parameters:

  • key
    (str) –

    The configuration key to validate.

  • value

    The value to validate.

Raises:

  • TypeError

    If the value is not of the expected type.

  • ValueError

    If the value is out of the allowed range or length.

radio

Radio configuration module for PySquared.

This module provides classes for handling and validating radio configuration parameters, including support for both FSK and LoRa modulation schemes.

Classes:

  • RadioConfig

    Handles top-level radio configuration and validation.

  • FSKConfig

    Handles FSK-specific configuration and validation.

  • LORAConfig

    Handles LoRa-specific configuration and validation.

Usage

Instantiate RadioConfig with a dictionary of radio parameters. Use the validate method to check if a given key/value pair is valid according to the radio schema.

FSKConfig

FSKConfig(fsk_dict: dict)

Handles FSK-specific radio configuration and validation.

Attributes:

  • broadcast_address (int) –

    Broadcast address for FSK.

  • node_address (int) –

    Node address for FSK.

  • modulation_type (int) –

    Modulation type for FSK.

  • FSK_SCHEMA (dict) –

    Validation schema for FSK configuration keys.

Parameters:

  • fsk_dict
    (dict) –

    Dictionary containing FSK configuration values.

LORAConfig

LORAConfig(lora_dict: dict)

Handles LoRa-specific radio configuration and validation.

Attributes:

  • ack_delay (float) –

    Acknowledgement delay in seconds.

  • coding_rate (int) –

    Coding rate for LoRa.

  • cyclic_redundancy_check (bool) –

    CRC enabled flag.

  • spreading_factor (Literal[6, 7, 8, 9, 10, 11, 12]) –

    LoRa spreading factor.

  • transmit_power (int) –

    Transmit power in dBm.

  • LORA_SCHEMA (dict) –

    Validation schema for LoRa configuration keys.

Parameters:

  • lora_dict
    (dict) –

    Dictionary containing LoRa configuration values.

RadioConfig

RadioConfig(radio_dict: dict)

Handles radio configuration and validation for PySquared.

Attributes:

  • license (str) –

    The radio license identifier.

  • modulation (Literal['LoRa', 'FSK']) –

    The modulation type.

  • transmit_frequency (int) –

    The transmission frequency in MHz.

  • start_time (int) –

    The radio start time in seconds.

  • fsk (FSKConfig) –

    FSK-specific configuration handler.

  • lora (LORAConfig) –

    LoRa-specific configuration handler.

  • RADIO_SCHEMA (dict) –

    Validation schema for radio configuration keys.

Methods:

  • validate

    Validates a radio configuration value against its schema.

Parameters:

  • radio_dict
    (dict) –

    Dictionary containing radio configuration values.

validate
validate(key: str, value) -> None

Validates a radio configuration value against its schema.

Parameters:

  • key
    (str) –

    The configuration key to validate.

  • value

    The value to validate.

Raises:

  • KeyError

    If the key is not found in any schema.

  • TypeError

    If the value is not of the expected type or not allowed.

  • ValueError

    If the value is out of the allowed range.

detumble

detumble Module

This module provides functions for satellite detumbling using magnetorquers. Includes vector math utilities and the main dipole calculation for attitude control.

Functions:

  • dot_product

    Computes the dot product of two 3-element vectors.

  • gain_func

    Returns the gain value for the detumble control law.

  • magnetorquer_dipole

    Calculates the required dipole moment for the magnetorquers to detumble the satellite.

  • x_product

    Computes the cross product of two 3-element vectors.

dot_product

dot_product(vector1: tuple, vector2: tuple) -> float

Computes the dot product of two 3-element vectors.

Parameters:

  • vector1

    (tuple) –

    First vector (length 3).

  • vector2

    (tuple) –

    Second vector (length 3).

Returns:

  • float ( float ) –

    The dot product of the two vectors.

gain_func

gain_func()

Returns the gain value for the detumble control law.

Returns:

  • float

    Gain value (default 1.0).

magnetorquer_dipole

magnetorquer_dipole(mag_field: tuple, ang_vel: tuple) -> list

Calculates the required dipole moment for the magnetorquers to detumble the satellite.

Parameters:

  • mag_field

    (tuple) –

    The measured magnetic field vector (length 3).

  • ang_vel

    (tuple) –

    The measured angular velocity vector (length 3).

Returns:

  • list ( list ) –

    The dipole moment vector to be applied (length 3).

x_product

x_product(vector1: tuple, vector2: tuple) -> list

Computes the cross product of two 3-element vectors.

Parameters:

  • vector1

    (tuple) –

    First vector (length 3).

  • vector2

    (tuple) –

    Second vector (length 3).

Returns:

  • list ( list ) –

    The cross product vector (length 3).

hardware

Modules:

burnwire

Modules:

manager

Modules:

burnwire

Classes:

BurnwireManager
BurnwireManager(logger: Logger, enable_burn: DigitalInOut, fire_burn: DigitalInOut, enable_logic: bool = True)

Bases: BurnwireProto

Class for managing burnwire ports.

:param Logger logger: Logger instance for logging messages. :param Digitalio enable_burn: A pin used for enabling the initial stage of a burnwire circuit. :param Digitalio fire_burn: A pin used for enabling a specific burnwire port. :param bool enable_logic: Boolean defining whether the burnwire load switches are enabled when True or False. Defaults to True.

Methods:

  • burn

    Fires the burnwire for a specified amount of time

burn
burn(timeout_duration: float = 5.0) -> bool

Fires the burnwire for a specified amount of time

:param float timeout_duration: The max amount of time to keep the burnwire on for.

:return: A Boolean indicating whether the burn occurred successfully :rtype: bool

:raises Exception: If there is an error toggling the burnwire pins.

busio

busio Module

This module provides functions for initializing and configuring SPI and I2C buses on the PySquared satellite hardware. Includes retry logic for robust hardware initialization and error handling.

Functions:

  • initialize_i2c_bus

    Initializes an I2C bus with the specified parameters. Includes retry logic.

  • initialize_spi_bus

    Initializes and configures an SPI bus with the specified parameters.

initialize_i2c_bus

initialize_i2c_bus(logger: Logger, scl: Pin, sda: Pin, frequency: Optional[int]) -> I2C

Initializes an I2C bus with the specified parameters. Includes retry logic.

Parameters:

  • logger
    (Logger) –

    Logger instance to log messages.

  • scl
    (Pin) –

    The pin to use for the SCL signal.

  • sda
    (Pin) –

    The pin to use for the SDA signal.

  • frequency
    (Optional[int]) –

    The baudrate of the I2C bus (default 100000).

Raises:

  • HardwareInitializationError

    If the I2C bus fails to initialize.

Returns:

  • I2C ( I2C ) –

    The initialized I2C object.

initialize_spi_bus

initialize_spi_bus(logger: Logger, clock: Pin, mosi: Optional[Pin] = None, miso: Optional[Pin] = None, baudrate: Optional[int] = 100000, phase: Optional[int] = 0, polarity: Optional[int] = 0, bits: Optional[int] = 8) -> SPI

Initializes and configures an SPI bus with the specified parameters.

Parameters:

  • logger
    (Logger) –

    Logger instance to log messages.

  • clock
    (Pin) –

    The pin to use for the clock signal.

  • mosi
    (Optional[Pin], default: None ) –

    The pin to use for the MOSI signal.

  • miso
    (Optional[Pin], default: None ) –

    The pin to use for the MISO signal.

  • baudrate
    (Optional[int], default: 100000 ) –

    The baudrate of the SPI bus (default 100000).

  • phase
    (Optional[int], default: 0 ) –

    The phase of the SPI bus (default 0).

  • polarity
    (Optional[int], default: 0 ) –

    The polarity of the SPI bus (default 0).

  • bits
    (Optional[int], default: 8 ) –

    The number of bits per transfer (default 8).

Raises:

  • HardwareInitializationError

    If the SPI bus fails to initialize.

Returns:

  • SPI ( SPI ) –

    The initialized SPI object.

decorators

decorators Module

This module provides decorators for hardware initialization and error handling, including retry logic with exponential backoff for robust hardware setup.

Functions:

  • with_retries

    Decorator that retries hardware initialization with exponential backoff.

with_retries

with_retries(max_attempts: int = 3, initial_delay: float = 1.0)

Decorator that retries hardware initialization with exponential backoff.

Parameters:

  • max_attempts
    (int, default: 3 ) –

    Maximum number of attempts to try initialization (default 3).

  • initial_delay
    (float, default: 1.0 ) –

    Initial delay in seconds between attempts (default 1.0).

Raises:

  • HardwareInitializationError

    If all attempts fail, the last exception is raised.

Returns:

  • function

    The result of the decorated function if successful.

digitalio

digitalio Module

This module provides functions for initializing DigitalInOut pins on the PySquared satellite hardware. Includes retry logic for robust hardware initialization and error handling.

Functions:

  • initialize_pin

    Initializes a DigitalInOut pin with the specified direction and initial value.

initialize_pin

initialize_pin(logger: Logger, pin: Pin, direction: Direction, initial_value: bool) -> DigitalInOut

Initializes a DigitalInOut pin with the specified direction and initial value.

Parameters:

  • logger
    (Logger) –

    The logger instance to log messages.

  • pin
    (Pin) –

    The pin to initialize.

  • direction
    (Direction) –

    The direction of the pin.

  • initial_value
    (bool) –

    The initial value of the pin (default is True).

Raises:

  • HardwareInitializationError

    If the pin fails to initialize.

Returns:

  • DigitalInOut ( DigitalInOut ) –

    The initialized DigitalInOut object.

imu

Modules:

manager

Modules:

lsm6dsox

Classes:

LSM6DSOXManager
LSM6DSOXManager(logger: Logger, i2c: I2C, address: int)

Bases: IMUProto, TemperatureSensorProto

Manager class for creating LIS2MDL IMU instances. The purpose of the manager class is to hide the complexity of IMU initialization from the caller. Specifically we should try to keep adafruit_lsm6ds to only this manager class.

:param Logger logger: Logger instance for logging messages. :param busio.I2C i2c: The I2C bus connected to the chip. :param int address: The I2C address of the IMU.

:raises HardwareInitializationError: If the IMU fails to initialize.

Methods:

  • get_acceleration

    Get the acceleration data from the inertial measurement unit.

  • get_gyro_data

    Get the gyroscope data from the inertial measurement unit.

  • get_temperature

    Get the temperature reading from the inertial measurement unit, if available.

get_acceleration
get_acceleration() -> tuple[float, float, float] | None

Get the acceleration data from the inertial measurement unit.

:return: A tuple containing the x, y, and z acceleration values in m/s^2 or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

get_gyro_data
get_gyro_data() -> tuple[float, float, float] | None

Get the gyroscope data from the inertial measurement unit.

:return: A tuple containing the x, y, and z angular acceleration values in radians per second or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

get_temperature
get_temperature() -> float | None

Get the temperature reading from the inertial measurement unit, if available.

:return: The temperature in degrees Celsius or None if not available. :rtype: float | None

:raises Exception: If there is an error retrieving the temperature value.

magnetometer

Modules:

manager

Modules:

lis2mdl

Classes:

  • LIS2MDLManager

    Manager class for creating LIS2MDL magnetometer instances.

LIS2MDLManager
LIS2MDLManager(logger: Logger, i2c: I2C)

Bases: MagnetometerProto

Manager class for creating LIS2MDL magnetometer instances. The purpose of the manager class is to hide the complexity of magnetometer initialization from the caller. Specifically we should try to keep adafruit_lis2mdl to only this manager class.

:param Logger logger: Logger instance for logging messages. :param busio.I2C i2c: The I2C bus connected to the chip.

:raises HardwareInitializationError: If the magnetometer fails to initialize.

Methods:

  • get_vector

    Get the magnetic field vector from the magnetometer.

get_vector
get_vector() -> tuple[float, float, float] | None

Get the magnetic field vector from the magnetometer.

:return: A tuple containing the x, y, and z magnetic field values in Gauss or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

radio

Modules:

manager

Modules:

base

Classes:

  • BaseRadioManager

    Base class for radio managers (CircuitPython compatible).

BaseRadioManager
BaseRadioManager(logger: Logger, radio_config: RadioConfig, **kwargs: object)

Bases: RadioProto

Base class for radio managers (CircuitPython compatible).

:param Logger logger: Logger instance for logging messages. :param RadioConfig radio_config: Radio configuration object. :param Flag use_fsk: Flag to determine whether to use FSK or LoRa mode. :param Any kwargs: Hardware-specific arguments (e.g., spi, cs, rst).

:raises HardwareInitializationError: If the radio fails to initialize after retries.

Methods:

  • get_max_packet_size

    Get the maximum packet size supported by the radio.

  • get_modulation

    Get the modulation mode from the initialized radio hardware.

  • get_rssi

    Get the RSSI of the last received packet.

  • modify_config

    Modify a specific radio configuration parameter.

  • receive

    Receive data from the radio.

  • send

    Send data over the radio.

  • set_modulation

    Request a change in the radio modulation mode.

get_max_packet_size
get_max_packet_size() -> int

Get the maximum packet size supported by the radio.

:return: The maximum packet size in bytes.

get_modulation
get_modulation() -> Type[RadioModulation]

Get the modulation mode from the initialized radio hardware.

:return: The current modulation mode of the hardware.

:raises NotImplementedError: If not implemented by subclass.

get_rssi
get_rssi() -> int

Get the RSSI of the last received packet.

:return: The RSSI of the last received packet. :raises NotImplementedError: If not implemented by subclass. :raises Exception: If querying the hardware fails.

modify_config
modify_config(key: str, value) -> None

Modify a specific radio configuration parameter.

Must be implemented by subclasses.

:param str key: The configuration parameter key to modify. :param value: The new value to set for the parameter. :raises NotImplementedError: If not implemented by subclass.

receive
receive(timeout: Optional[int] = None) -> bytes | None

Receive data from the radio.

Must be implemented by subclasses.

:param int | None timeout: Optional receive timeout in seconds.If None, use the default timeout. :return: The received data as bytes, or None if no data was received.

:raises NotImplementedError: If not implemented by subclass. :raises Exception: If receiving fails unexpectedly.

send
send(data: bytes) -> bool

Send data over the radio.

Must be implemented by subclasses.

:param bytes data: The data to send.

set_modulation
set_modulation(modulation: Type[RadioModulation]) -> None

Request a change in the radio modulation mode. This change might take effect immediately or after a reset, depending on implementation.

:param RadioModulation modulation: The desired modulation mode.

rfm9x

Classes:

  • RFM9xManager

    Manager class implementing RadioProto for RFM9x radios.

RFM9xManager
RFM9xManager(logger: Logger, radio_config: RadioConfig, spi: SPI, chip_select: DigitalInOut, reset: DigitalInOut)

Bases: BaseRadioManager, TemperatureSensorProto

Manager class implementing RadioProto for RFM9x radios.

:param Logger logger: Logger instance for logging messages. :param RadioConfig radio_config: Radio config object. :param Flag use_fsk: Flag to determine whether to use FSK or LoRa mode. :param busio.SPI spi: The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected. :param ~digitalio.DigitalInOut chip_select: A DigitalInOut object connected to the chip's CS/chip select line. :param ~digitalio.DigitalInOut reset: A DigitalInOut object connected to the chip's RST/reset line.

:raises HardwareInitializationError: If the radio fails to initialize after retries.

Methods:

  • get_modulation

    Get the modulation mode from the initialized RFM9x radio.

  • get_rssi

    Get the RSSI of the last received packet.

  • get_temperature

    Get the temperature reading from the radio sensor.

  • modify_config

    Modify a specific radio configuration parameter.

  • receive

    Receive data from the radio.

  • send

    Send data over the radio.

  • set_modulation

    Request a change in the radio modulation mode.

get_modulation
get_modulation() -> Type[RadioModulation]

Get the modulation mode from the initialized RFM9x radio.

get_rssi
get_rssi() -> int

Get the RSSI of the last received packet.

get_temperature
get_temperature() -> float

Get the temperature reading from the radio sensor.

modify_config
modify_config(key: str, value) -> None

Modify a specific radio configuration parameter.

:param str key: The configuration parameter key to modify. :param object value: The new value to set for the parameter. :raises ValueError: If the key is not recognized or invalid for the current radio type.

receive
receive(timeout: Optional[int] = None) -> bytes | None

Receive data from the radio.

:param int | None timeout: Optional receive timeout in seconds. If None, use the default timeout. :return: The received data as bytes, or None if no data was received.

send
send(data: bytes) -> bool

Send data over the radio.

Must be implemented by subclasses.

:param bytes data: The data to send.

set_modulation
set_modulation(modulation: Type[RadioModulation]) -> None

Request a change in the radio modulation mode. This change might take effect immediately or after a reset, depending on implementation.

:param RadioModulation modulation: The desired modulation mode.

sx126x

Classes:

  • SX126xManager

    Manager class implementing RadioProto for SX126x radios.

SX126xManager
SX126xManager(logger: Logger, radio_config: RadioConfig, spi: SPI, chip_select: DigitalInOut, irq: DigitalInOut, reset: DigitalInOut, gpio: DigitalInOut)

Bases: BaseRadioManager

Manager class implementing RadioProto for SX126x radios.

:param Logger logger: Logger instance for logging messages. :param RadioConfig radio_config: Radio configuration object. :param Flag use_fsk: Flag to determine whether to use FSK or LoRa mode. :param busio.SPI spi: The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected. :param ~digitalio.DigitalInOut chip_select: Chip select pin. :param ~digitalio.DigitalInOut irq: Interrupt request pin. :param ~digitalio.DigitalInOut reset: Reset pin. :param ~digitalio.DigitalInOut gpio: General purpose IO pin (used by SX126x).

:raises HardwareInitializationError: If the radio fails to initialize after retries.

Methods:

  • get_max_packet_size

    Get the maximum packet size supported by the radio.

  • get_modulation

    Get the modulation mode from the initialized SX126x radio.

  • get_rssi

    Get the RSSI of the last received packet.

  • modify_config

    Modify a specific radio configuration parameter.

  • receive

    Receive data from the radio.

  • send

    Send data over the radio.

  • set_modulation

    Request a change in the radio modulation mode.

get_max_packet_size
get_max_packet_size() -> int

Get the maximum packet size supported by the radio.

:return: The maximum packet size in bytes.

get_modulation
get_modulation() -> Type[RadioModulation]

Get the modulation mode from the initialized SX126x radio.

get_rssi
get_rssi() -> int

Get the RSSI of the last received packet.

:return: The RSSI of the last received packet. :raises NotImplementedError: If not implemented by subclass. :raises Exception: If querying the hardware fails.

modify_config
modify_config(key: str, value) -> None

Modify a specific radio configuration parameter.

Must be implemented by subclasses.

:param str key: The configuration parameter key to modify. :param value: The new value to set for the parameter. :raises NotImplementedError: If not implemented by subclass.

receive
receive(timeout: Optional[int] = None) -> bytes | None

Receive data from the radio.

:param int | None timeout: Optional receive timeout in seconds. If None, use the default timeout. :return: The received data as bytes, or None if no data was received.

send
send(data: bytes) -> bool

Send data over the radio.

Must be implemented by subclasses.

:param bytes data: The data to send.

set_modulation
set_modulation(modulation: Type[RadioModulation]) -> None

Request a change in the radio modulation mode. This change might take effect immediately or after a reset, depending on implementation.

:param RadioModulation modulation: The desired modulation mode.

sx1280

Classes:

  • SX1280Manager

    Manager class implementing RadioProto for SX1280 radios.

SX1280Manager
SX1280Manager(logger: Logger, radio_config: RadioConfig, spi: SPI, chip_select: DigitalInOut, reset: DigitalInOut, busy: DigitalInOut, frequency: float, txen: DigitalInOut, rxen: DigitalInOut)

Bases: BaseRadioManager

Manager class implementing RadioProto for SX1280 radios.

:param Logger logger: Logger instance for logging messages. :param RadioConfig radio_config: Radio configuration object. :param Flag use_fsk: Flag to determine whether to use FSK or LoRa mode. :param busio.SPI spi: The SPI bus connected to the chip. Ensure SCK, MOSI, and MISO are connected. :param ~digitalio.DigitalInOut chip_select: Chip select pin. :param ~digitalio.DigitalInOut busy: Interrupt request pin. :param ~digitalio.DigitalInOut reset: Reset pin. :param ~digitalio.DigitalInOut txen: Transmit enable pin. :param ~digitalio.DigitalInOut rxen: Receive enable pin.

:raises HardwareInitializationError: If the radio fails to initialize after retries.

Methods:

  • get_max_packet_size

    Get the maximum packet size supported by the radio.

  • get_modulation

    Get the modulation mode from the initialized SX1280 radio.

  • get_rssi

    Get the RSSI of the last received packet.

  • modify_config

    Modify a specific radio configuration parameter.

  • receive

    Receive data from the radio.

  • send

    Send data over the radio.

  • set_modulation

    Request a change in the radio modulation mode.

get_max_packet_size
get_max_packet_size() -> int

Get the maximum packet size supported by the radio.

:return: The maximum packet size in bytes.

get_modulation
get_modulation() -> Type[RadioModulation]

Get the modulation mode from the initialized SX1280 radio.

get_rssi
get_rssi() -> int

Get the RSSI of the last received packet.

:return: The RSSI of the last received packet. :raises NotImplementedError: If not implemented by subclass. :raises Exception: If querying the hardware fails.

modify_config
modify_config(key: str, value) -> None

Modify a specific radio configuration parameter.

Must be implemented by subclasses.

:param str key: The configuration parameter key to modify. :param value: The new value to set for the parameter. :raises NotImplementedError: If not implemented by subclass.

receive
receive(timeout: Optional[int] = None) -> bytes | None

Receive data from the radio.

:param int | None timeout: Optional receive timeout in seconds. If None, use the default timeout. :return: The received data as bytes, or None if no data was received.

send
send(data: bytes) -> bool

Send data over the radio.

Must be implemented by subclasses.

:param bytes data: The data to send.

set_modulation
set_modulation(modulation: Type[RadioModulation]) -> None

Request a change in the radio modulation mode. This change might take effect immediately or after a reset, depending on implementation.

:param RadioModulation modulation: The desired modulation mode.

modulation

Classes:

  • FSK

    FSK modulation mode.

  • LoRa

    LoRa modulation mode.

  • RadioModulation

    Base type for radio modulation modes.

FSK

Bases: RadioModulation

FSK modulation mode.

LoRa

Bases: RadioModulation

LoRa modulation mode.

RadioModulation

Base type for radio modulation modes.

packetizer

Modules:

packet_manager

Classes:

PacketManager
PacketManager(logger: Logger, radio: RadioProto, license: str, send_delay: float = 0.2)

Methods:

listen
listen(timeout: Optional[int] = None) -> bytes | None

Listen for data from the radio.

:param int | None timeout: Optional receive timeout in seconds. If None, use the default timeout. :return: The received data as bytes, or None if no data was received.

send
send(data: bytes) -> bool

Send data

send_acknowledgement
send_acknowledgement() -> None

Send an acknowledgment to the radio.

logger

logger Module

Logger class for handling logging messages with different severity levels. Logs can be output to standard output or saved to a file (functionality to be implemented). Includes colorized output and error counting.

Classes:

  • LogLevel

    Defines log level constants for Logger.

  • Logger

    Logger class for handling logging messages with different severity levels.

LogLevel

Defines log level constants for Logger.

Logger

Logger(error_counter: Counter, log_level: int = NOTSET, colorized: bool = False)

Logger class for handling logging messages with different severity levels.

Attributes:

  • _error_counter (Counter) –

    Counter for error occurrences.

  • _log_level (int) –

    Current log level.

  • colorized (bool) –

    Whether to colorize output.

Parameters:

  • error_counter

    (Counter) –

    Counter for error occurrences.

  • log_level

    (int, default: NOTSET ) –

    Initial log level.

  • colorized

    (bool, default: False ) –

    Whether to colorize output.

Methods:

  • critical

    Log a message with severity level CRITICAL.

  • debug

    Log a message with severity level DEBUG.

  • error

    Log a message with severity level ERROR.

  • get_error_count

    Returns the current error count.

  • info

    Log a message with severity level INFO.

  • warning

    Log a message with severity level WARNING.

critical

critical(message: str, err: Exception, **kwargs) -> None

Log a message with severity level CRITICAL.

Parameters:

  • message
    (str) –

    The log message.

  • err
    (Exception) –

    The exception to log.

  • **kwargs

    Additional key/value pairs to include in the log.

debug

debug(message: str, **kwargs) -> None

Log a message with severity level DEBUG.

Parameters:

  • message
    (str) –

    The log message.

  • **kwargs

    Additional key/value pairs to include in the log.

error

error(message: str, err: Exception, **kwargs) -> None

Log a message with severity level ERROR.

Parameters:

  • message
    (str) –

    The log message.

  • err
    (Exception) –

    The exception to log.

  • **kwargs

    Additional key/value pairs to include in the log.

get_error_count

get_error_count() -> int

Returns the current error count.

Returns:

  • int ( int ) –

    The number of errors logged.

info

info(message: str, **kwargs) -> None

Log a message with severity level INFO.

Parameters:

  • message
    (str) –

    The log message.

  • **kwargs

    Additional key/value pairs to include in the log.

warning

warning(message: str, **kwargs) -> None

Log a message with severity level WARNING.

Parameters:

  • message
    (str) –

    The log message.

  • **kwargs

    Additional key/value pairs to include in the log.

nvm

The NVM package is a collection of functionality that interacts with non-volatile memory

Modules:

counter

counter Module

This module provides the Counter class for managing 8-bit counters stored in non-volatile memory (NVM) on CircuitPython devices.

Classes:

  • Counter

    Counter class for managing 8-bit counters stored in non-volatile memory.

Counter

Counter(index: int)

Counter class for managing 8-bit counters stored in non-volatile memory.

Attributes:

  • _index (int) –

    The index of the counter in the NVM datastore.

  • _datastore (ByteArray) –

    The NVM datastore.

Parameters:

  • index
    (int) –

    The index of the counter in the datastore.

Raises:

  • ValueError

    If NVM is not available.

Methods:

  • get

    Returns the value of the counter.

  • get_name

    get_name returns the name of the counter

  • increment

    Increases the counter by one, with 8-bit rollover.

get
get() -> int

Returns the value of the counter.

Returns:

  • int ( int ) –

    The current value of the counter.

get_name
get_name() -> str

get_name returns the name of the counter

increment
increment() -> None

Increases the counter by one, with 8-bit rollover.

flag

flag Module

This module provides the Flag class for managing boolean flags stored in non-volatile memory (NVM) on CircuitPython devices.

Classes:

  • Flag

    Flag class for managing boolean flags stored in non-volatile memory.

Flag

Flag(index: int, bit_index: int)

Flag class for managing boolean flags stored in non-volatile memory.

Attributes:

  • _index (int) –

    The index of the flag (byte) in the NVM datastore.

  • _bit (int) –

    The bit index within the byte.

  • _datastore (ByteArray) –

    The NVM datastore.

  • _bit_mask (int) –

    Bitmask for the flag's bit position.

Parameters:

  • index
    (int) –

    The index of the flag (byte) in the datastore.

  • bit_index
    (int) –

    The index of the bit within the byte.

Raises:

  • ValueError

    If NVM is not available.

Methods:

  • get

    Returns the value of the flag.

  • get_name

    get_name returns the name of the flag

  • toggle

    Sets or clears the flag value.

get
get() -> bool

Returns the value of the flag.

Returns:

  • bool ( bool ) –

    The current value of the flag.

get_name
get_name() -> str

get_name returns the name of the flag

toggle
toggle(value: bool) -> None

Sets or clears the flag value.

Parameters:

  • value
    (bool) –

    If True, sets the flag; if False, clears the flag.

power_health

Classes:

PowerHealth

PowerHealth(logger: Logger, config: Config, power_monitor: PowerMonitorProto)

Methods:

  • get

    Get the power health

get

get() -> NOMINAL | DEGRADED | CRITICAL | UNKNOWN

Get the power health

protos

This module defines hardware agnostic protocols for accessing devices with certain features. This allows for flexibility in the design of the system, enabling the use of different hardware implementations without changing the code that uses them.

CircuitPython does not support Protocols directly, but these classes can still be used to define an interface for type checking and ensuring multi-device compatibility.

https://docs.python.org/3/library/typing.html#typing.Protocol

Modules:

  • burnwire

    Protocol defining the interface for a burnwire port.

  • imu

    Protocol defining the interface for an Inertial Measurement Unit (IMU).

  • magnetometer

    Protocol defining the interface for a Magnetometer.

  • power_monitor

    Protocol defining the interface for a Power Monitor.

  • radio

    Protocol defining the interface for a radio.

  • rtc

    Protocol defining the interface for a Real Time Clock (RTC).

  • temperature_sensor

    Protocol defining the interface for a temperature sensor.

burnwire

Protocol defining the interface for a burnwire port.

Classes:

BurnwireProto

Methods:

  • burn

    Fires the burnwire for a specified amount of time

burn
burn(timeout_duration: float) -> bool

Fires the burnwire for a specified amount of time

:param float timeout_duration: The max amount of time to keep the burnwire on for.

:return: A Boolean indicating whether the burn occurred successfully :rtype: bool

:raises Exception: If there is an error toggling the burnwire pins.

imu

Protocol defining the interface for an Inertial Measurement Unit (IMU).

Classes:

IMUProto

Methods:

  • get_acceleration

    Get the acceleration data from the inertial measurement unit.

  • get_gyro_data

    Get the gyroscope data from the inertial measurement unit.

get_acceleration
get_acceleration() -> tuple[float, float, float] | None

Get the acceleration data from the inertial measurement unit.

:return: A tuple containing the x, y, and z acceleration values in m/s^2 or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

get_gyro_data
get_gyro_data() -> tuple[float, float, float] | None

Get the gyroscope data from the inertial measurement unit.

:return: A tuple containing the x, y, and z angular acceleration values in radians per second or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

magnetometer

Protocol defining the interface for a Magnetometer.

Classes:

MagnetometerProto

Methods:

  • get_vector

    Get the magnetic field vector from the magnetometer.

get_vector
get_vector() -> tuple[float, float, float] | None

Get the magnetic field vector from the magnetometer.

:return: A tuple containing the x, y, and z magnetic field values in Gauss or None if not available. :rtype: tuple[float, float, float] | None

:raises Exception: If there is an error retrieving the values.

power_monitor

Protocol defining the interface for a Power Monitor.

Classes:

PowerMonitorProto

Methods:

get_bus_voltage
get_bus_voltage() -> float | None

Get the bus voltage from the power monitor.

:return: The bus voltage in volts :rtype: float | None

get_current
get_current() -> float | None

Get the current from the power monitor.

:return: The current in amps :rtype: float | None

get_shunt_voltage
get_shunt_voltage() -> float | None

Get the shunt voltage from the power monitor.

:return: The shunt voltage in volts :rtype: float | None

radio

Protocol defining the interface for a radio.

Classes:

RadioProto

Methods:

  • get_max_packet_size

    Get the maximum packet size supported by the radio.

  • get_modulation

    Get the currently configured or active radio modulation mode.

  • get_rssi

    Get the RSSI of the last received packet.

  • modify_config

    Modify a specific radio configuration parameter.

  • receive

    Receive data from the radio.

  • send

    Send data over the radio.

  • set_modulation

    Request a change in the radio modulation mode.

get_max_packet_size
get_max_packet_size() -> int

Get the maximum packet size supported by the radio.

:return: The maximum packet size in bytes. :rtype: int

get_modulation
get_modulation() -> Type[RadioModulation]

Get the currently configured or active radio modulation mode.

:return: The current modulation mode. :rtype: RadioModulation

get_rssi
get_rssi() -> int

Get the RSSI of the last received packet.

:return: The RSSI value in dBm. :rtype: int

:raises NotImplementedError: If not implemented by subclass.

modify_config
modify_config(key: str, value) -> None

Modify a specific radio configuration parameter.

:param str key: The configuration parameter key to modify. :param value: The new value to set for the parameter. :raises NotImplementedError: If not implemented by subclass.

receive
receive(timeout: Optional[int] = None) -> Optional[bytes]

Receive data from the radio.

:param int | None timeout: Optional receive timeout in seconds. If None, use the default timeout. :return: The received data as bytes, or None if no data was received. :rtype: Optional[bytes]

send
send(data: bytes) -> bool

Send data over the radio.

:param bytes data: The data to send. :return: True if the send was successful. :rtype: bool

set_modulation
set_modulation(modulation: Type[RadioModulation]) -> None

Request a change in the radio modulation mode. This change might take effect immediately or after a reset, depending on implementation.

:param RadioModulation modulation: The desired modulation mode.

rtc

Protocol defining the interface for a Real Time Clock (RTC).

Classes:

RTCProto

Methods:

  • set_time

    Set the time on the real time clock.

set_time
set_time(year: int, month: int, date: int, hour: int, minute: int, second: int, weekday: int) -> None

Set the time on the real time clock.

:param year: The year value (0-9999) :param month: The month value (1-12) :param date: The date value (1-31) :param hour: The hour value (0-23) :param minute: The minute value (0-59) :param second: The second value (0-59) :param weekday: The nth day of the week (0-6), where 0 represents Sunday and 6 represents Saturday

:raises Exception: If there is an error setting the values.

temperature_sensor

Protocol defining the interface for a temperature sensor.

Classes:

TemperatureSensorProto

Methods:

get_temperature
get_temperature() -> float | None

Get the temperature reading of the sensor.

:return: The temperature in degrees Celsius or None if not available. :rtype: float | None

rtc

Modules:

manager

Modules:

microcontroller

Classes:

  • MicrocontrollerManager

    Class for interfacing with the Microcontroller's Real Time Clock (RTC) via CircuitPython.

MicrocontrollerManager
MicrocontrollerManager()

Bases: RTCProto

Class for interfacing with the Microcontroller's Real Time Clock (RTC) via CircuitPython.

rtc.RTC is a singleton and does not need to be stored as a class variable.

Required on every boot to ensure the RTC is ready for use

Methods:

  • set_time

    Updates the Microcontroller's Real Time Clock (RTC) to the date and time passed

set_time
set_time(year: int, month: int, date: int, hour: int, minute: int, second: int, weekday: int) -> None

Updates the Microcontroller's Real Time Clock (RTC) to the date and time passed

:param year: The year value (0-9999) :param month: The month value (1-12) :param date: The date value (1-31) :param hour: The hour value (0-23) :param minute: The minute value (0-59) :param second: The second value (0-59) :param day_of_week: The nth day of the week (0-6), where 0 represents Sunday and 6 represents Saturday

rv3028

Classes:

  • RV3028Manager

    Manager class for creating RV3028 RTC instances.

RV3028Manager
RV3028Manager(logger: Logger, i2c: I2C)

Bases: RTCProto

Manager class for creating RV3028 RTC instances. The purpose of the manager class is to hide the complexity of RTC initialization from the caller. Specifically we should try to keep adafruit_lis2mdl to only this manager class.

:param Logger logger: Logger instance for logging messages. :param busio.I2C i2c: The I2C bus connected to the chip.

:raises HardwareInitializationError: If the RTC fails to initialize.

Methods:

  • set_time

    Set the time on the real time clock.

set_time
set_time(year: int, month: int, date: int, hour: int, minute: int, second: int, weekday: int) -> None

Set the time on the real time clock.

:param year: The year value (0-9999) :param month: The month value (1-12) :param date: The date value (1-31) :param hour: The hour value (0-23) :param minute: The minute value (0-59) :param second: The second value (0-59) :param weekday: The nth day of the week (0-6), where 0 represents Sunday and 6 represents Saturday

:raises Exception: If there is an error setting the values.

sleep_helper

sleep_helper Module

This module provides the SleepHelper class for managing safe sleep and hibernation modes for the PySquared satellite. It ensures the satellite sleeps for specified durations while maintaining system safety and watchdog activity.

Classes:

  • SleepHelper

    Class responsible for sleeping the Satellite to conserve power.

SleepHelper

Class responsible for sleeping the Satellite to conserve power.

Attributes:

  • cubesat (Satellite) –

    The Satellite object.

  • logger (Logger) –

    Logger instance for logging events and errors.

  • watchdog (Watchdog) –

    Watchdog instance for system safety.

  • config (Config) –

    Configuration object.

Parameters:

  • cubesat

    (Satellite) –

    The Satellite object.

  • logger

    (Logger) –

    Logger instance for logging events and errors.

  • watchdog

    (Watchdog) –

    Watchdog instance for system safety.

  • config

    (Config) –

    Configuration object.

Methods:

  • safe_sleep

    Puts the Satellite to sleep for a specified duration, in seconds.

safe_sleep

safe_sleep(duration) -> None

Puts the Satellite to sleep for a specified duration, in seconds.

Allows for a maximum sleep duration of the longest_allowable_sleep_time field specified in config

Parameters:

  • duration
    (int) –

    Specified time, in seconds, to sleep the Satellite for.

watchdog

watchdog Module

This module provides the Watchdog class for managing the hardware watchdog timer on the PySquared satellite. The watchdog helps ensure system reliability by requiring periodic "petting" to prevent system resets.

Classes:

  • Watchdog

    Watchdog class for managing the hardware watchdog timer.

Watchdog

Watchdog(logger: Logger, pin: Pin)

Watchdog class for managing the hardware watchdog timer.

Attributes:

  • _log (Logger) –

    Logger instance for logging messages.

  • _digital_in_out (DigitalInOut) –

    Digital output for controlling the watchdog pin.

Parameters:

  • logger

    (Logger) –

    Logger instance for logging messages.

  • pin

    (Pin) –

    Pin to use for the watchdog timer.

Raises:

  • HardwareInitializationError

    If the pin fails to initialize.

Methods:

  • pet

    Pets (resets) the watchdog timer to prevent system reset.

pet

pet() -> None

Pets (resets) the watchdog timer to prevent system reset.