Core Concepts
The Engine
The C++ Engine is Kenate's secret weapon. It runs 1000 times per second, calling your Python code with precision timing. Fast? Understatement.
How It Works
When you call engine.start(), the C++ Engine takes over. It runs an infinite loop at exactly 1000Hz (once per millisecond).
On every tick, it:
- Reads all sensor values from hardware
- Calls your active State's
on_update()method - Writes motor commands to hardware
- Handles any state transitions you requested
Why 1000Hz?
Smooth robot motion requires fast, consistent updates. If your loop runs at inconsistent speeds (50ms one tick, 200ms the next), your robot's movements will be jerky and unpredictable.
The C++ Engine guarantees each tick is exactly 1ms. This is critical for:
- PID controllers (smooth motor ramping)
- Sensor fusion (combining gyro + accelerometer data)
- Precise timing for servos and stepper motors
Engine API
| Method | Description |
|---|---|
| register_state(name, state) | Add a state to the engine |
| start(initial_state) | Start the loop (blocking) |
| stop() | Cleanly terminate the loop |
| pause() | Freeze (motors hold position) |
| resume() | Resume from pause |
| get_current_state_name() | Returns active state name |
| load_config(path) | Load hardware.toml |
State Transitions
To switch states, call self.change_state("NewState")from inside your current state. The Engine handles the rest:
# When you call self.change_state("Alert"):
# 1. Current state's on_exit() is called
# 2. New state's on_enter() is called
# 3. Next tick calls new state's on_update()Clean transitions, every time.