API Reference

This API reference provides detailed information about the classes and methods available in the inno_control library.

The library is designed for communicating with laboratory control systems and physical devices such as the classic Cart-Pole benchmark system. It provides:

LabDevice — a base class for serial device communication.
CartPole — a specific implementation for an inverted pendulum on a cart.

Below are the available classes with their methods and detailed docstrings.

LabDevice

class inno_control.devices.LabDevice(port, baudrate=921600, timeout=1.0)[source]

Bases: object

Base class for laboratory equipment communication via a serial interface.

This class defines a generic interface to connect to any lab device (e.g., a motor controller, sensor board, or actuator) that communicates using a serial port. It provides core methods for connecting, disconnecting, sending commands, and reading responses. Specific devices should extend this base class and implement any custom initialization logic in _initialize_device.

Parameters:

port (str)
baudrate (int)
timeout (float)

_port

Serial port used to connect to the device.

Type:: str

_baudrate

Communication speed in baud.

Type:: int

_timeout

Timeout for serial operations.

Type:: float

_connection

Active serial connection.

Type:: serial.Serial

__init__(port, baudrate=921600, timeout=1.0)[source]

Establish the serial connection with the lab device.

Opens the serial port with the specified configuration and calls _initialize_device to perform any device-specific setup after connection.

Raises:

DeviceConnectionError – If the serial port cannot be opened.

Parameters:

port (str)
baudrate (int)
timeout (float)

connect(do_init_activity=True)[source]

Connect to devicce.

Parameters:: do_init_activity (bool) – True if you want to initilize device.
Return type:: None

disconnect()[source]

Closes the serial port if it is open and clears the connection attribute.

Return type:: None

__enter__()[source]: Context manager entry point

__exit__(exc_type, exc_val, exc_tb)[source]: Context manager exit point

Cart-Pole System

The Cart-Pole is a classic non-linear control benchmark. It models an inverted pendulum mounted on a motorized cart that can move horizontally. The control objective is to apply forces to the cart so that the pendulum remains upright.

The equations of motion are derived from Newton’s second law and the Lagrangian method:

\[(M + m) \ddot{x} + m l \ddot{\theta} \cos \theta - m l \dot{\theta}^2 \sin \theta = F\]

\[I \ddot{\theta} + m l \ddot{x} \cos \theta + m g l \sin \theta = 0\]

where:

\(x\) is the horizontal position of the cart,
\(\theta\) is the angle of the pendulum from vertical,
\(M\) is the mass of the cart,
\(m\) is the mass of the pendulum,
\(l\) is the distance to the pendulum center of mass,
\(I\) is the moment of inertia of the pendulum about its center of mass,
\(F\) is the horizontal force applied to the cart,
\(g\) is the acceleration due to gravity.

The Cart-Pole system is inherently unstable and is a popular testbed for advanced control algorithms such as LQR, swing-up control, and reinforcement learning.

class inno_control.devices.CartPole(port, baudrate=921600, timeout=1.0)[source]

Bases: LabDevice

Interface for controlling and reading from a physical Cart-Pole system via an ESP32 device.

This class allows you to initialize, start, stop, and control a real inverted pendulum on a cart. It communicates via serial port, sending commands to the onboard controller which drives the cart motor to balance the pendulum upright by applying horizontal forces.

The Cart-Pole is a classic non-linear control benchmark: the goal is to keep the pendulum in unstable equilibrium by continuously adjusting the cart position.

Parameters:

port (str)
baudrate (int)
timeout (float)

_state

Current state of the system, can be ‘UNKNOWN’, ‘READY’, or ‘STARTED’.

Type:: str

__init__(port, baudrate=921600, timeout=1.0)[source]

Create a new CartPole device interface.

Opens a serial connection to the ESP32 device that controls the cart motor and reads sensor data.

Parameters:

port (str) – Serial port (e.g., ‘/dev/ttyUSB0’, ‘COM3’).
baudrate (int, optional) – Serial communication speed in baud. Defaults to 921600.
timeout (float, optional) – Timeout for serial reads/writes in seconds. Defaults to 1.0.

re_init()[source]: TODO

start_experimnet()[source]

Begin the balancing experiment.

This method puts the system into active balancing mode, where the motor controller will apply control efforts to keep the pendulum upright.

Raises:: DeviceCommandError – If the system does not confirm that balancing has started.
Return type:: None

get_state()[source]

Get the current state of the Cart-Pole device.

Returns:: Current system state: ‘UNKNOWN’, ‘READY’, or ‘STARTED’.
Return type:: str

get_joint_state()[source]

Read the current physical state of the cart and pole.

When the experiment is running, this reads data such as the cart position, velocity, pendulum angle, and angular velocity from the onboard sensors.

Returns:: Raw sensor data as received from the ESP32.
Return type:: str
Raises:: DeviceCommandError – If called when the system is not running.

stop_experiment()[source]

Stop the balancing experiment and switch the system back to idle.

This sends a command to stop applying control forces and returns the system to a safe idle state. It verifies that the system acknowledges the mode change.

Raises:: DeviceCommandError – If the system fails to return to ‘READY’ mode.
Return type:: None

set_joint_efforts(effort)[source]

Send a control effort command to the cart motor.

This lets you directly set the motor control effort or apply a specific force, for example, to test responses or run custom controllers.

Parameters:: effort (str) – Effort command string (e.g., ‘EFFORT=0.2’). The format must match what the device firmware expects.
Raises:: DeviceCommandError – If the effort command cannot be sent.
Return type:: None

stop_motor()[source]

TODO

Return type:: None

help_me()[source]

TODO

Return type:: None

Exceptions

inno_control.exceptions: alias of <module ‘inno_control.exceptions’ from ‘/home/runner/work/total_control/total_control/inno_control/src/inno_control/exceptions.py’>