bonicos

The Python SDK for BonicBot robots. Drive the base, move the arms, run navigation and mapping, and read live sensor telemetry — from your own laptop or from a program running on the robot itself, with the same code either way.

pip install bonicos

from bonicos import BonicBot

with BonicBot("192.168.1.50") as robot:
    robot.move_forward(speed=0.3, duration=2)
    robot.move_left_arm(shoulder=45, elbow=30)
    print(robot.get_battery(), "V")
# motors stopped and the connection closed, even on an exception

Requires Python 3.10+. Pure Python — the same wheel runs on a laptop, a Raspberry Pi, or a Jetson.

Connecting

bonicos talks to the robot over your local network. You need the robot's address:

robot = BonicBot("192.168.1.50")

If the environment already knows which robot you mean, a bare BonicBot() works. That's the case when your program runs on the robot, where BONICOS_HOST is set for you — so a script you developed on your laptop needs no edits to run on the robot. You can also set that variable yourself, or install bonicos[discovery] to find a robot by mDNS.

On a classroom LAN with several robots, robot_id is optional but useful: pin it and the connection only succeeds against that specific robot —

robot = BonicBot("192.168.1.50", robot_id="M1_001")

— and it doubles as the filter for bonicos[discovery] when you don't know the address either (BonicBot(robot_id="M1_001")). Leave it off for the common case of one robot, or a host you already trust.

Anyone on the same network can connect. There is no authentication yet — robot_id is a wrong-robot guard, not a password. Run robots on a network you trust.

No robot handy? BonicBot.simulated() connects to a fake one instead — driving, arms, and telemetry all behave for real, with no network and no hardware required.

What you can do

Full reference with every signature: API.md.

Movement calls block until the robot actually gets there — move_left_arm(...) returns when the joint has converged on its target, not when the command was merely acknowledged.

Not yet working on the robot

Some commands are accepted and silently do nothing on current robot firmware. Your code runs; that actuator just doesn't move. They are marked 🔌 stub in API.md:

• Nav2 lifecycle — start_navigation, stop_navigation
• servo_single

Head expression (set_expression, look) is live on A and S series, and every HeadMode expression is a real face on both. The LED-matrix display_* calls are A series only — the S display shows preset expressions and refuses them. All of it needs the base stack up, and a robot with no face display answers with an error rather than pretending.

Everything else in the table above is live. Vision pipelines (face/pose/object detection), autonomous exploration, and recorded sequences are not in this release.

On Lite robots (s1-lite, a2-lite) navigation and mapping are not stubs — they are absent, and raise CommandError rather than silently doing nothing. Motion, arms, display, speech, sensors and camera all work. The SDK does not check capability at runtime and the robot does not advertise it: API.md is the reference for what each model supports — every section carries an On Lite line.

Safety

• Use the context-manager form (with BonicBot(...) as robot:) or call robot.close() in a finally. Both stop the robot on the way out.
• The robot stops its own motors if it stops hearing from you (roughly 400 ms), so a crashed script or a dropped connection will not leave it driving. That backstop covers driving only — a navigation goal keeps running, so cancel it explicitly if you're bailing out.

Installing extras

pip install bonicos              # driving, arms, navigation, telemetry
pip install bonicos[camera]      # + camera frames (aiortc, numpy)
pip install bonicos[discovery]   # + find a robot by mDNS

Each extra reports what's missing if you use a feature without it, rather than failing with an import error.

Documentation

• API.md — every class and method, with blocking behaviour and worked examples. Also the capability reference: each section's On Lite line says what that model supports.
• PROTOCOL.md — the wire protocol, if you're writing your own client or working on the robot side.
• examples/ — eleven runnable scripts, laptop or robot.
• CHANGELOG.md — what changed between releases, including breaking changes and how to migrate.

License

MIT — see LICENSE. © Autobonics Pvt Ltd.