hardware

Bms ¶

Bms(
    *, battery_low_threshold: float | None = None, **kwargs
)

Bases: Module, ABC

The BMS module communicates with a simple battery management system over a serial connection.

The BMS module provides measured voltages as an event.

Parameters:

Name	Type	Description	Default
`battery_low_threshold`	`float \| None`	If provided, the BATTERY_LOW event will be emitted when the battery percentage gets below this threshold.	`None`

is_above_percent ¶

is_above_percent(value: float) -> bool

Returns whether the battery is charged above the given percentage.

is_above_voltage ¶

is_above_voltage(value: float) -> bool

Returns whether the battery voltage is above the given value.

is_below_percent ¶

is_below_percent(value: float) -> bool

Returns whether the battery is charged below the given percentage.

is_below_voltage ¶

is_below_voltage(value: float) -> bool

Returns whether the battery voltage is below the given value.

Events¶

Name	Description
STATE_UPDATED	The BMS state has been updated with new data (argument: `BmsState`)
CHARGING_STARTED	The battery started charging
CHARGING_STOPPED	The battery stopped charging
BATTERY_LOW	The battery percentage is below the threshold

BmsHardware ¶

BmsHardware(
    robot_brain: RobotBrain,
    *,
    expander: ExpanderHardware | None = None,
    name: str = "bms",
    rx_pin: int = 26,
    tx_pin: int = 27,
    baud: int = 9600,
    num: int = 1,
    charge_detect_threshold: float = -0.4,
    **kwargs
)

Bases: Bms, ModuleHardware

This module implements the hardware interface for the BMS module.

Parameters:

Name	Type	Description	Default
`expander`	`ExpanderHardware \| None`	If provided, the BMS module will use the expander module to create the serial connection.	`None`
`name`	`str`	The name of the BMS module.	`'bms'`
`rx_pin`	`int`	The GPIO pin number to use for the RX line.	`26`
`tx_pin`	`int`	The GPIO pin number to use for the TX line.	`27`
`baud`	`int`	The baud rate to use for the serial communication.	`9600`
`num`	`int`	The serial port index to use for creating the serial connection.	`1`
`charge_detect_threshold`	`float`	The threshold current to use for charging detection.	`-0.4`

Events¶

Name	Description
STATE_UPDATED	The BMS state has been updated with new data (argument: `BmsState`)
CHARGING_STARTED	The battery started charging
CHARGING_STOPPED	The battery stopped charging
BATTERY_LOW	The battery percentage is below the threshold

BmsSimulation ¶

BmsSimulation(*, voltage_per_second: float = 0.0, **kwargs)

Bases: Bms, ModuleSimulation

This module simulates a BMS module.

Parameters:

Name	Type	Description	Default
`voltage_per_second`	`float`	The voltage change per second. Positive for charging, negative for discharging.	`0.0`

Events¶

Name	Description
STATE_UPDATED	The BMS state has been updated with new data (argument: `BmsState`)
CHARGING_STARTED	The battery started charging
CHARGING_STOPPED	The battery stopped charging
BATTERY_LOW	The battery percentage is below the threshold

Bumper ¶

Bumper(estop: EStop | None, **kwargs)

Bases: Module, ABC

A module that detects when a bumper is triggered.

Events¶

Name	Description
BUMPER_TRIGGERED	a bumper was triggered (argument: the bumper name)
BUMPER_RELEASED	a bumper was released (argument: the bumper name)

BumperHardware ¶

BumperHardware(
    robot_brain: RobotBrain,
    *,
    expander: ExpanderHardware | None = None,
    name: str = "bumper",
    pins: dict[str, int],
    estop: EStop | None = None,
    inverted: bool = False
)

Bases: Bumper, ModuleHardware

Hardware implementation of the bumper module.

The module expects a dictionary of pin names and pin numbers. If an e-stop is provided, the module will not trigger bumpers if the e-stop is active.

Events¶

Name	Description
BUMPER_TRIGGERED	a bumper was triggered (argument: the bumper name)
BUMPER_RELEASED	a bumper was released (argument: the bumper name)

BumperSimulation ¶

BumperSimulation(estop: EStop | None, **kwargs)

Bases: Bumper, ModuleSimulation

Simulation of the bumper module.

Events¶

Name	Description
BUMPER_TRIGGERED	a bumper was triggered (argument: the bumper name)
BUMPER_RELEASED	a bumper was released (argument: the bumper name)

Communication ¶

Communication()

Bases: ABC

This abstract module defines an interface for communicating with a microcontroller.

Besides sending and receiving messages a communication module provides a property whether communication is possible. It can also provide a piece of debug UI.

EStop ¶

EStop(**kwargs)

Bases: Module, ABC

A module that detects when the e-stop is triggered.

The module has a boolean field active that is true when the e-stop is triggered.

There is also a boolean field is_soft_estop_active that is true when the soft e-stop is active. It can be set to true or false by calling set_soft_estop(active: bool).

active `property` ¶

active: bool

Whether any hardware e-stop or the soft e-stop is active.

is_soft_estop_active `property` ¶

is_soft_estop_active: bool

Whether the soft e-stop is active.

set_soft_estop `async` ¶

set_soft_estop(active: bool) -> None

Set the soft e-stop to the given state.

Events¶

Name	Description
ESTOP_TRIGGERED	the e-stop was triggered (argument: the e-stop name)
ESTOP_RELEASED	the e-stop was released (argument: the e-stop name)

EStopHardware ¶

EStopHardware(
    robot_brain: RobotBrain,
    *,
    name: str = "estop",
    pins: dict[str, int],
    inverted: bool = True
)

Bases: EStop, ModuleHardware

Hardware implementation of the e-stop module.

The module expects a dictionary of pin names and pin numbers.

Events¶

Name	Description
ESTOP_TRIGGERED	the e-stop was triggered (argument: the e-stop name)
ESTOP_RELEASED	the e-stop was released (argument: the e-stop name)

EStopSimulation ¶

EStopSimulation(**kwargs)

Bases: EStop, ModuleSimulation

Simulation of the e-stop module.

activate `async` ¶

activate() -> None

Activate the soft e-stop.

deactivate `async` ¶

deactivate() -> None

Deactivate the soft e-stop.

Events¶

Name	Description
ESTOP_TRIGGERED	the e-stop was triggered (argument: the e-stop name)
ESTOP_RELEASED	the e-stop was released (argument: the e-stop name)

EspNotReadyException ¶

Bases: Exception

Raised when trying to use the ESP before it is ready.

Events¶

Name	Description
ESP_CONNECTED	ESP has been connected and Lizard is ready to use
LINE_RECEIVED	a line has been received from the microcontroller (argument: line as string)
FLASH_P0_COMPLETE	flashing p0 was successful and 'Replica complete' was received

ExpanderHardware ¶

ExpanderHardware(
    robot_brain: RobotBrain,
    *,
    name: str = "p0",
    serial: SerialHardware,
    boot: int = 25,
    enable: int = 14
)

Bases: ModuleHardware

The expander module represents a second ESP microcontroller connected to the core ESP via serial.

Gnss ¶

Gnss()

Bases: ABC

A GNSS module that provides measurements from a GNSS receiver.

Events¶

Name	Description
NEW_MEASUREMENT	a new measurement has been received (argument: `GnssMeasurement`)

GnssHardware ¶

GnssHardware(
    *,
    antenna_pose: Pose | None,
    reconnect_interval: float = 3.0
)

Bases: Gnss

This hardware module connects to a Septentrio SimpleRTK3b (Mosaic-H) GNSS receiver.

Parameters:

Name	Type	Description	Default
`antenna_pose`	`Pose \| None`	the pose of the main antenna in the robot's coordinate frame (yaw: direction to the auxiliary antenna)	required
`reconnect_interval`	`float`	the interval to wait before reconnecting to the device	`3.0`

GnssSimulation ¶

GnssSimulation(
    *,
    pose_provider: PoseProvider,
    lat_std_dev: float = 0.01,
    lon_std_dev: float = 0.01,
    heading_std_dev: float = 0.01,
    interval: float = 1.0,
    latency: float = 0.0,
    gps_quality: GpsQuality = GpsQuality.RTK_FIXED
)

Bases: Gnss

Simulation of a GNSS receiver.

Parameters:

Name	Type	Description	Default
`pose_provider`	`PoseProvider`	the pose provider to use for the simulation	required
`lat_std_dev`	`float`	the standard deviation of the latitude in meters	`0.01`
`lon_std_dev`	`float`	the standard deviation of the longitude in meters	`0.01`
`heading_std_dev`	`float`	the standard deviation of the heading in degrees	`0.01`
`gps_quality`	`GpsQuality`	the quality of the GPS signal	`RTK_FIXED`
`interval`	`float`	the interval between measurements in seconds	`1.0`
`latency`	`float`	the simulated measurement latency in seconds	`0.0`

Imu ¶

Imu(offset_rotation: Rotation | None = None, **kwargs)

Bases: Module

A module that provides measurements from an IMU.

Events¶

Name	Description
NEW_MEASUREMENT	a new measurement has been received (argument: ImuMeasurement)

ImuHardware ¶

ImuHardware(
    robot_brain: RobotBrain,
    name: str = "imu",
    *,
    min_gyro_calibration: float = 1.0,
    **kwargs
)

Bases: Imu, ModuleHardware

A hardware module that handles the communication with an IMU.

Events¶

Name	Description
NEW_MEASUREMENT	a new measurement has been received (argument: ImuMeasurement)

ImuSimulation ¶

ImuSimulation(
    *,
    pose_provider: PoseProvider,
    interval: float = 0.1,
    roll: float = 0.0,
    pitch: float = 0.0,
    roll_noise: float = 0.0,
    pitch_noise: float = 0.0,
    yaw_noise: float = 0.0,
    **kwargs
)

Bases: Imu, ModuleSimulation

Simulation of an IMU.

Events¶

Name	Description
NEW_MEASUREMENT	a new measurement has been received (argument: ImuMeasurement)

Robot ¶

Robot(modules: list[Module])

Bases: ABC

A robot that consists of a number of modules.

It can be either a hardware robot or a simulation.

RobotBrain ¶

RobotBrain(
    communication: Communication,
    *,
    enable_esp_on_startup: bool = True,
    use_espresso: bool = False,
    heartbeat_interval: float | None = None
)

This module manages the communication with a Zauberzeug Robot Brain.

It expects a communication object, which is used for the actual read and write operations. Besides providing some basic methods like configuring or restarting the microcontroller, it augments and verifies checksums for each message.

It also keeps track of the clock offset between the microcontroller and the host system, which is used to synchronize the hardware time with the system time. The clock offset is calculated by comparing the hardware time with the system time and averaging the differences over a number of samples. If the offset changes significantly, a notification is sent and the offset history is cleared.

Initialize the RobotBrain and connect to the microcontroller.

Parameters:

Name	Type	Description	Default
`communication`	`Communication`	The communication object to use for reading and writing messages	required
`enable_esp_on_startup`	`bool`	Whether to enable the ESP on startup (default: `True`)	`True`
`use_espresso`	`bool`	Whether to use the new espresso.py for controlling the ESP instead of the old flash.py (default: `False`)	`False`
`heartbeat_interval`	`float \| None`	If not `None`, the interval in seconds at which to send heartbeat messages to the ESP (default: `None`)	`None`

send `async` ¶

send(msg: str, *, force: bool = False) -> None

Send a Lizard command to the ESP.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The Lizard command to send	required
`force`	`bool`	Whether to send the message even if the ESP is not ready	`False`

Raises:

Type	Description
`EspNotReadyException`	When the ESP is not ready and force is `False`

send_and_await `async` ¶

send_and_await(
    msg: str,
    ack: str,
    *,
    timeout: float = float("inf"),
    force: bool = False
) -> str | None

Send a Lizard command to the ESP and await a response.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The Lizard command to send	required
`ack`	`str`	The first word of the response message to wait for	required
`timeout`	`float`	Response timeout	`float('inf')`
`force`	`bool`	Whether to send the message even if the ESP is not ready	`False`

Returns:

Type	Description
`str \| None`	The response message or `None` if the timeout is reached

Raises:

Type	Description
`EspNotReadyException`	When the ESP is not ready and force is `False`

send_heartbeat `async` ¶

send_heartbeat() -> None

Send a core.keep_alive() command to the microcontroller to let it know that RoSys is still running.

Events¶

Name	Description
ESP_CONNECTED	ESP has been connected and Lizard is ready to use
LINE_RECEIVED	a line has been received from the microcontroller (argument: line as string)
FLASH_P0_COMPLETE	flashing p0 was successful and 'Replica complete' was received

RobotHardware ¶

RobotHardware(
    modules: list[Module], robot_brain: RobotBrain
)

Bases: Robot

A robot that consists of hardware modules.

It generates Lizard code, forwards output to the hardware modules and sends commands to the robot brain.

en3_off `async` ¶

en3_off() -> None

Activate the EN3 software emergency stop to cut power to the robot.

en3_on `async` ¶

en3_on() -> None

Release the EN3 software emergency stop to provide power to the robot.

rdyp_off `async` ¶

rdyp_off() -> None

Deactivate RDYP to cut power to the robot's hardware.

rdyp_on `async` ¶

rdyp_on() -> None

Activate RDYP to provide power to the robot's hardware.

Power will only be available if EN1, EN2 or EN3 are active.

RobotSimulation ¶

RobotSimulation(modules: list[Module])

Bases: Robot

A robot that consists of simulated modules.

It regularly calls the step method of all modules to allow them to update their internal state.

SerialCommunication ¶

SerialCommunication(
    *,
    device_path: str | None = None,
    baud_rate: int = 115200
)

Bases: Communication

This module implements a communication via a serial device with a given baud rate.

It contains a list of search paths for finding the serial device.

SerialHardware ¶

SerialHardware(
    robot_brain: RobotBrain,
    *,
    name: str = "serial",
    rx_pin: int = 26,
    tx_pin: int = 27,
    baud: int = 115200,
    num: int = 1
)

Bases: ModuleHardware

The serial module represents a serial connection with another device.

WebCommunication ¶

WebCommunication()

Bases: Communication

Remote connection to the Robot Brain's ESP.

This makes it possible to keep developing on your fast computer while communicating with the hardware components connected to a physical Robot Brain.

Wheels ¶

Wheels(**kwargs)

Bases: Module, ABC

This module represents wheels for a two-wheel differential drive.

Wheels can be moved using the drive methods and provide measured velocities as an event.

Events¶

Name	Description
VELOCITY_MEASURED	the wheel velocities have been measured (argument: list of `Velocity` objects)
POSE_UPDATED:	Emitted when the pose has been updated (argument: current `Pose`).

WheelsHardware ¶

WheelsHardware(
    robot_brain: RobotBrain,
    *,
    can: CanHardware,
    name: str = "wheels",
    left_can_address: int = 0,
    right_can_address: int = 256,
    m_per_tick: float = 0.01,
    width: float = 0.5,
    is_left_reversed: bool = False,
    is_right_reversed: bool = False
)

Bases: Wheels, ModuleHardware

This module implements wheels hardware.

Drive and stop commands are forwarded to a given Robot Brain. Velocities are read and emitted regularly.

Events¶

Name	Description
VELOCITY_MEASURED	the wheel velocities have been measured (argument: list of `Velocity` objects)
POSE_UPDATED:	Emitted when the pose has been updated (argument: current `Pose`).

WheelsSimulation ¶

WheelsSimulation(width: float = 0.5)

Bases: Wheels, ModuleSimulation, PoseProvider

This module simulates two wheels.

Drive and stop commands impact internal velocities (linear and angular). A simulated pose is regularly updated with these velocities, while the velocities are emitted as an event.

POSE_UPDATED `instance-attribute` ¶

POSE_UPDATED: Event[Pose] = Event()

Emitted when the pose has been updated (argument: current Pose).

_pose `instance-attribute` ¶

_pose: Pose = Pose(time=time())

Provides the actual pose of the robot which can alter due to slippage.

angular_velocity `instance-attribute` ¶

angular_velocity: float = 0

The current angular velocity of the robot.

friction_factor `instance-attribute` ¶

friction_factor: float = 0.0

The factor of friction for the wheels (0 = no friction, 1 = full friction).

inertia_factor `instance-attribute` ¶

inertia_factor: float = 0.0

The factor of inertia for the wheels (0 = no inertia, 1 = full inertia).

is_blocking `instance-attribute` ¶

is_blocking: bool = False

If True, the wheels are blocking and the robot will not move.

linear_velocity `instance-attribute` ¶

linear_velocity: float = 0

The current linear velocity of the robot.

slip_factor_left `instance-attribute` ¶

slip_factor_left: float = 0

The factor of slippage for the left wheel (0 = no slippage, 1 = full slippage).

slip_factor_right `instance-attribute` ¶

slip_factor_right: float = 0

The factor of slippage for the right wheel (0 = no slippage, 1 = full slippage).

width `instance-attribute` ¶

width: float = width

The distance between the wheels -- used to calculate actual drift when slip_factor_* is used.

Events¶

Name	Description
VELOCITY_MEASURED	the wheel velocities have been measured (argument: list of `Velocity` objects)
POSE_UPDATED:	Emitted when the pose has been updated (argument: current `Pose`).

hardware

Bms ¶

is_above_percent ¶

is_above_voltage ¶

is_below_percent ¶

is_below_voltage ¶

Events¶

BmsHardware ¶

Events¶

BmsSimulation ¶

Events¶

Bumper ¶

Events¶

BumperHardware ¶

Events¶

BumperSimulation ¶

Events¶

Communication ¶

EStop ¶

active property ¶

is_soft_estop_active property ¶

set_soft_estop async ¶

Events¶

EStopHardware ¶

Events¶

EStopSimulation ¶

activate async ¶

deactivate async ¶

Events¶

EspNotReadyException ¶

Events¶

ExpanderHardware ¶

Gnss ¶

Events¶

GnssHardware ¶

GnssSimulation ¶

Imu ¶

Events¶

ImuHardware ¶

Events¶

ImuSimulation ¶

Events¶

Robot ¶

RobotBrain ¶

send async ¶

send_and_await async ¶

send_heartbeat async ¶

Events¶

RobotHardware ¶

en3_off async ¶

en3_on async ¶

rdyp_off async ¶

rdyp_on async ¶

RobotSimulation ¶

SerialCommunication ¶

SerialHardware ¶

WebCommunication ¶

Wheels ¶

Events¶

WheelsHardware ¶

Events¶

WheelsSimulation ¶

POSE_UPDATED instance-attribute ¶

_pose instance-attribute ¶

angular_velocity instance-attribute ¶

friction_factor instance-attribute ¶

inertia_factor instance-attribute ¶

is_blocking instance-attribute ¶

linear_velocity instance-attribute ¶

slip_factor_left instance-attribute ¶

slip_factor_right instance-attribute ¶

width instance-attribute ¶

Events¶

active `property` ¶

is_soft_estop_active `property` ¶

set_soft_estop `async` ¶

activate `async` ¶

deactivate `async` ¶

send `async` ¶

send_and_await `async` ¶

send_heartbeat `async` ¶

en3_off `async` ¶

en3_on `async` ¶

rdyp_off `async` ¶

rdyp_on `async` ¶

POSE_UPDATED `instance-attribute` ¶

_pose `instance-attribute` ¶

angular_velocity `instance-attribute` ¶

friction_factor `instance-attribute` ¶

inertia_factor `instance-attribute` ¶

is_blocking `instance-attribute` ¶

linear_velocity `instance-attribute` ¶

slip_factor_left `instance-attribute` ¶

slip_factor_right `instance-attribute` ¶

width `instance-attribute` ¶