BB NSK

Beam Bots board support for the Nerves Starter Kit and its Balance Bot add-on — a two-wheeled self-balancing robot with an e-paper panel, four NeoPixels and a web interface you drive it from.

Two halves. The drivers and control loops that are the same on every one of these boards ship as modules; everything a particular robot gets to choose is written into your project by an Igniter task.

Installation

mix igniter.new my_bot --with nerves.new --with-args="--target trellis" \
  --install bb_nsk
cd my_bot

Then add subsystems one at a time, each leaving a robot that does something it couldn't before:

mix bb_nsk.add_wheels   # its wheels turn
mix bb_nsk.add_imu      # it knows which way up it is
mix bb_nsk.add_balance  # it stands up

Or skip to the end:

mix bb_nsk.cheat

Build and burn:

MIX_TARGET=trellis mix firmware
MIX_TARGET=trellis mix burn

Tasks

Task	What it adds	What the robot can then do
`bb_nsk.install`	Nerves system, device tree provisioning, robot module, persistent parameters	boot on the right device tree
`bb_nsk.add_wheels`	two DRV8837 wheel actuators and the motor deadband parameter	drive its wheels
`bb_nsk.add_imu`	BMI323, a Mahony filter, and the lean and heading sensors	say which way up it is
`bb_nsk.add_balance`	the balance loop, its states, its commands and its gains	stand up
`bb_nsk.add_leds`	the NeoPixel state indicator	show its state across the room
`bb_nsk.add_display`	the e-paper panel and the status screen	draw its own status
`bb_nsk.add_environment_sensor`	the base board's HTS221	report the air around it
`bb_nsk.add_wifi`	an access point it brings up when it has no network to join	be reached with nothing configured
`bb_nsk.add_web`	Phoenix, a dashboard, a drive pad and a wifi setup page	be driven from a phone
`bb_nsk.cheat`	all of the above, in order	—
`bb_nsk.doctor`	nothing; run it on the board	tell you which of five things is missing

Every add_* task takes --robot, and every one is safe to run twice.

Hardware


SoC	Allwinner T113-S4 (dual Cortex-A7, `armv7`)
Nerves system	`nerves_system_trellis` `~> 0.5`
Device tree	`nsk-balance-bot`, selected by the provisioning this installs
Motors	two N20 gearmotors through a DRV8837, on `pwmchip0` channels 2–5
IMU	BMI323 at `0x68` on `i2c-0`
LEDs	four NeoPixels on `ledc`
Display	4.2" 400x300 e-paper, UC8276 controller, one bit per pixel
Environment	HTS221 at `0x5F` on `i2c-0`

Requirements

Elixir 1.19 or later
A Nerves project targeting :trellis
nerves_system_trellis ~> 0.5 — 0.4 and earlier have no balance bot device tree at all, and crossing to 0.5 needs a FEL reflash rather than mix upload

bb_nsk.add_display and bb_nsk.add_environment_sensor add git dependencies — eink, emerge and hts221 are prototype drivers not yet on Hex.

Known limitations

No simulation. A generated project needs the hardware; it won't boot on your laptop yet.
No odometry, and no position hold. There are no encoders, so two of the four states an inverted pendulum has are unobservable. It balances while drifting.
No buttons or battery telemetry yet. Both are behind the board's STM32, which speaks an ASCII protocol over /dev/ttyS2 and comes pre-flashed. This is deliberately left undone — it is the obvious thing to build once the robot is standing up, and a generator for it will follow.

bb — the robotics framework
bb_sensor_bmi323 — the IMU driver
bb_estimator_ahrs — the orientation filters
bb_parameter_store_cubdb — parameter persistence
bb_liveview — the dashboard the web interface mounts

Acknowledgements

Gus Workman and Protolux Electronics for the Nerves Starter Kit, and for the eink driver the panel is drawn through
Frederic Cambus for the Spleen font the panel is set in
The Emerge project, which rasterises the panel's screens

Licence

Apache-2.0. See LICENSE.txt.