Bring your own body

Put the GrowBot brain on your own robot. The brain runs in the GrowBot app and picks the moves. Your robot's chip plays them. Today every move is two values, left and right, and your chip decides what they do.

Start here

Building something?

Drop a note in the GrowBot Discord with what you're making and we'll help!

Add an arm experimental

A stock Pico robot can carry a small arm of up to four 180° hobby servos next to its wheels or legs. You move it by hand on the arm page. The brain cannot move the arm yet: it still sends only left and right. Brain control comes later, with the plan for bodies with more servos.

1. Wiring, power off. Wheels or legs stay on sockets 0 and 1. The arm goes on sockets 2, 3, 4 and 5 (base, shoulder, elbow, grip). Leave 8 and 9 empty: the chip software checks those pins for a servo chip at power-on. Other free sockets are 6, 7 and 10 to 15. This needs the Waveshare Pico Servo Driver from the build guide, where each socket number is its Pico pin (socket 2 is GP2). Boards with a PCA9685 servo chip, and other direct-wire boards like the Kitronik Simply Robotics, are not supported: the arm stays off.
2. Power. Six servos can draw more current than the kit's AA pack handles well. We recommend two 18650 cells in series (2S, 7.4 V) in a holder with a protection board, on the board's battery input: Waveshare rates it 4.5 to 26 V and gives the servos 5 V. Use short, thick wires. A separate servo supply needs its ground joined to the board's ground. Never power servos from USB: do every USB step below with the battery off and the arm unplugged, and never connect USB and the battery at the same time.
3. Install the chip software with the USB installer in build step 02, as usual. It never installs the arm, so a robot without the two files below runs exactly as before.
4. Copy two files onto the Pico, next to main.py: arm_body.py and arm_config.py. In Thonny, open each one and use File, Save as, Raspberry Pi Pico, with the same name. Or run mpremote cp arm_body.py arm_config.py :. Copy within a few seconds of plugging in USB: once the robot is online, its watchdog restarts it 8 seconds after you stop it. A cut-off copy is fine, just unplug, plug back in and copy again.
5. Set arm_config.py. Give each joint its socket, min and max. Its numbers are a cautious guess, not a measured arm, so start narrow and widen once you know where each joint binds. After a restart the Pico's console (Thonny) prints one arm: line with the sockets it drives, or why the arm stays off.
6. Open growbot.dev/tester/arm.html, enter the pairing code and move one joint at a time. Close GrowBot first: GrowBot ends its moves with a stop, and a stop lets the arm go limp.

How it behaves: every move is clamped to the joint's min and max, and a joint that is holding moves no faster than 60° a second. The arm holds its pose after a move. It lets go on STOP, when the robot loses its connection, after 2 minutes with no new move, and 15 s after the arm page closes, sleeps or loses its signal. The grip lets go 15 s after your last move, so a grip squeezing something does not cook its servo. The speed and these times are set in arm_config.py. A servo cannot report where it is, so after the arm lets go a joint can sag, and the next move first snaps it back to where it was at the servo's own speed, one joint at a time. Keep hands clear and start with small moves. Switching on works the same way: each joint goes to rest, one at a time, then lets go, so leave the arm at rest before you switch off. When the robot restarts itself (a lost Wi-Fi, the watchdog) the arm stays limp until the next move. Nothing watches for a fall while you use the arm page, so keep a finger near STOP. Nobody has run this on a real arm yet: tell us how yours goes in Discord.

How GrowBot bodies work, and where it's going

GrowBot is a brain meant to work in any body. Today it runs in your phone's browser: it thinks with a cloud AI model, uses the phone's sensors, and sends moves through our relay to your robot's chip.

So the phone does two jobs: it runs the brain, and its sensors are part of the robot. Walks and drives use the phone's motion sensor, so the phone rides on the robot. On a PC the app can gesture but refuses walks and drives, and a phone lying nearby reads its own tilt, not the robot's.

Later the brain could run on a nearby computer or inside the robot, with no phone.

Works today

• Any chip that follows the messages below can take moves from the brain.
• Wheels mode for two-motor rovers.
• More motors through your own chip software, as group or signal moves.

Coming soon

• One file per robot that lists every motor, so the brain can move each one by name. Gestures first, on a four-leg robot.
• A setup page for new bodies.

Technical reference

The app and your body meet at a relay, on the same pairing code. The relay forwards any JSON object and drops anything else; your chip maps the messages to hardware. For your own brain driving a stock robot, see agent-docs.

GrowBot app (phone) ──▶ relay  wss://growbot-relay.growbot.workers.dev/d/<code> ──▶ your machine

A body opens wss://growbot-relay.growbot.workers.dev/d/<code> and sends {"t":"hello","id":"<code>"} first. The app attaches to the same code with {"t":"attach"}. Make up your own: gb- followed by lowercase letters and digits, like gb-k7q2m9x4. The app lowercases what you type, and the relay treats upper and lower case as different codes.

Tell the app what you are

The app reads a body block that says what your robot is. The default is /v3/body.json. Each GrowBot saves its own copy the first time it wakes, and that copy wins from then on. To change it, save your soul file (brain, Settings, soul, save the file), edit its body, and load it back with "bring one in". These fields change what the app does:

Mode: ?wheels=1 turns on wheels mode for that link. To leave wheels mode, open the app without ?wheels=1. If your saved body declares wheels, change it there; ?wheels=0 won't override it. A ?wheels= link without ?id= won't reconnect to your last robot, so pair again.

Spins on legs: custom leg bodies use the older built-in spin. The stock two-leg body uses a newer trained spin when it can; ?normalspin=0 turns it off. Wheels pivot with their drive.

The wire, in full

What the live app sends: attach, then only pose, act (always "mode":"replace") and stop. It ignores anything else your body sends, like battery or sensor readings.

Mapping cookbook

Ways to use the left and right values on a robot that isn't two legs. It all happens in your chip software.

Differential drive: mower, tank tracks, rover, two motor RC car

l and r become wheel speeds, and 90 is stop. With the stock calibration (L_SIGN -1, like the legs), wheels mode sends forward as l below 90 and r above 90, so flip l first. Check your effective signs: saved wheel signs take precedence, and a body and phone declaring no signs use +1/+1 instead. Stopping on silence matters more here: on legs a stale pose is a held limb, on wheels it is a machine that keeps going.

l = 180 - l                        # undo the stock left mirror: forward is now both above 90
speed_left  = (l - 90) / 40.0      # -1.0 .. +1.0 across a 50..130 band
speed_right = (r - 90) / 40.0
if abs(speed_left)  < 0.06: speed_left  = 0    # deadband, motors buzz near zero
if abs(speed_right) < 0.06: speed_right = 0

Declare a band of [50,130] in your body block, clamp on the chip too, and make the auto-stop brake rather than coast. The stock chip software goes limp after 500ms of silence. Wheels mode sends a drive frame every 100ms, so use about 300ms.

Use wheels mode for rolling. It sends steady speeds, then 90,90 to stop. Don't map the leg walk onto wheels: it steps back and forth, so a rover twitches. Need throttle and yaw instead? Use l after the flip:

throttle = (l + r) / 2 - 90
yaw      = (l - r) / 2

Real example, a robot lawnmower. Someone put GrowBot on a Husqvarna Automower 310. The Pico chip software and write-up are at ports/automower. Its README was written before wheels mode existed: ignore its note that wheels mode is not live, leave GAIT_ROLL off, and use wheels mode. The numbers below are from that build:

• Your H bridge has to survive the pack. An 18V mower battery kills a DRV8833 (10.8V max) and a TB6612 (15V absolute max). BTS7960 / IBT-2 (5.5 to 27.5V, sign magnitude on two PWM pins) is the one that lives. The "43A" in every IBT-2 listing is an internal limit threshold, not a continuous rating: plan for about 10 to 15A continuous without extra heatsinking.
• Moving ESP32 wheel code to a Pico? machine.Timer(0) raises on rp2 (use -1), so the driver never starts and the board never boots. Pins 32 and 33 do not exist. GP23, 24, 25 and 29 belong to the Wi-Fi chip, so an ESP32 pin like 25 kills the radio.
• The boot wiggle is dangerous at scale. The stock chip software's power-on wiggle is harmless on a desk toy and drives a 10kg machine off its dock. Gate it behind a boot lockout that brakes through the whole sequence.

One steering servo plus a throttle: a normal RC car

l = 180 - l                                        # same flip as above
throttle = ((l - 90) + (r - 90)) / 2.0 / 40.0     # forward and back
steer    = ((l - 90) - (r - 90)) / 2.0 / 40.0     # -1 left .. +1 right

After the flip, forward is both values above 90, and a wheels-mode turn is a pivot: one side forward, one back. A car can't pivot, so this formula gives zero throttle with the wheels turned. Give a turn a minimum throttle so it becomes the car's tightest circle, or leave the car parked. The brain is not told either way.

Six servos, a hexapod, an arm

• Two degrees of freedom out of many. l and r drive shoulder and elbow, or pan and tilt, and the other joints hold a posture you choose.
• Gait parameters. Run the app in wheels mode and use the throttle and yaw split above: throttle sets stride, yaw sets turning, and your own gait engine runs at whatever rate it needs. The brain steers; your chip walks.
• Pose library. Round the pair to an index and play a whole body pose. Crude, effective, very readable on video.
• Keyframes as choreography. An act plan is a sequence with timings. Ignore the numbers and treat each step as a cue for a move of your own.

DC motors, steppers, ESCs, anything that is not a hobby servo

Map the value to whatever your driver wants inside one function, like apply_pair in the example below: PWM duty plus a direction pin, a velocity setpoint, a step target, an RC pulse. The rest of the code does not change.

Does my machine need Wi-Fi?

Something in the room has to reach the internet, because the app and the body meet at the relay, which is in the cloud. It does not have to be the machine:

• Machine is online itself (Pico W, ESP32, a Pi on Wi-Fi or ethernet). It dials the relay directly. This is the stock kit.
• Machine is dumb, a computer beside it is online. A laptop or a Pi runs the code below and passes the numbers on over USB serial, I2C, CAN, PWM or an RC transmitter module. An Arduino, a motor driver board, an old robot arm with a serial port: none of them touch the network.
• No machine at all. Point it at a simulator, a game, a plotter, a room full of lights. The app cannot tell.

Fully offline does not work today. The app is an https page, so it cannot reach a plain http board on your local network. That is why bodies dial out to the relay.

A whole body in 50 lines

Complete and working. It prints instead of moving anything. It keeps reading the socket while a move plays, so stop lands right away and the auto-stop keeps its own clock. Replace the two hardware functions and it drives a robot.

# growbot_body.py   ·   pip install websockets   ·   python growbot_body.py
import asyncio, json, websockets

RELAY = "wss://growbot-relay.growbot.workers.dev"
CODE  = "gb-k7q2m9x4"   # make up your own: gb- then lowercase letters and digits
DEADMAN = 0.5           # no pose for 500ms -> go safe. do not skip this one.

ROUTINES = {"wiggle": [{"l": 60, "r": 120, "ms": 400}, {"l": 120, "r": 60, "ms": 400},
                       {"l": 90,  "r": 90,  "ms": 300}]}

def apply_pair(l, r):     # <-- YOUR MACHINE. two numbers, 0..180, 90 = neutral / stop
    print("pair %6.1f %6.1f" % (l, r), flush=True)

def go_safe():            # <-- YOUR MACHINE. limp, brake, whatever safe is on your machine
    print("safe", flush=True)

# this toy jumps to each pair and holds it for ms. the stock chip software glides there
# over ms instead. for real motors, use act_engine.py.
async def play(steps):                       # runs as its OWN task so the socket stays live
    for s in steps:
        apply_pair(s.get("l", 90), s.get("r", 90))
        await asyncio.sleep(s.get("ms", 0) / 1000)
    go_safe()                                # natural end. a cancel means someone else took over

async def main():
    move = None
    def busy(): return move is not None and not move.done()
    def take_over():
        if busy(): move.cancel()
    async with websockets.connect("%s/d/%s" % (RELAY, CODE)) as ws:
        await ws.send(json.dumps({"t": "hello", "id": CODE}))   # this line makes you a body
        print("body online as", CODE, flush=True)
        streaming = False
        try:
            while True:
                try:
                    m = json.loads(await asyncio.wait_for(ws.recv(), timeout=DEADMAN))
                except asyncio.TimeoutError:
                    if streaming and not busy():             # auto-stop: silence = safe
                        go_safe(); streaming = False
                    continue
                t = m.get("t")
                if t == "pose":                              # a pose preempts a plan
                    take_over()
                    l, r = (float(x) for x in m.get("lr", "90,90").split(","))
                    apply_pair(l, r); streaming = True
                elif t in ("act", "routine"):
                    steps = m.get("steps") if t == "act" else ROUTINES.get(m.get("name", ""), [])
                    await ws.send(json.dumps({"t": "ack", "rid": m.get("rid"), "ok": 1,
                                              "queued_ms": sum(s.get("ms", 0) for s in steps or [])}))
                    take_over(); streaming = False           # ack FIRST, then start moving
                    move = asyncio.create_task(play(steps or []))
                elif t == "stop":
                    take_over(); streaming = False; go_safe()
                    await ws.send(json.dumps({"t": "ack", "rid": m.get("rid"), "ok": 1, "queued_ms": 0}))
        finally:
            take_over(); go_safe()                           # every exit path ends safe

asyncio.run(main())

Your own protocol, both ends

If you write both ends, you can send any messages you like over the relay, like more motors or sensor readings. Your own brain then takes the place of the phone app. The body is the loop above with t values you invent. Your brain sends attach instead of hello.

# brain side (your laptop). the body side answers with anything it wants.
await ws.send(json.dumps({"t":"attach","id":CODE,"code":CODE}))
await ws.send(json.dumps({"t":"joints","rid":1,
                          "q":[10,20,30,40,50,60,70,80,90,100,110,120],"ms":250}))
# ...and the body pushes sensors back up the same socket:
#   {"t":"telemetry","q":[...],"imu":{"pitch":3.2,"roll":-1.1},"load_a":0.42}

Keep hello and attach exactly as they are: that is how the relay tells the two sides apart.

Rules a body should honor

1. Auto-stop. When commands stop arriving, go safe: limp on legs, brake on wheels. This is the difference between a robot that stops when a phone drops off Wi-Fi and one that drives into a wall.
2. Heartbeat. Put "caps":["hb"] in your hello and send {"t":"hb"} every 15 s, so the relay notices when your body dies.
3. Ack immediately, then move. Reply to act, routine and stop within a few milliseconds and play the motion afterwards. Never block the socket for the length of a move.
4. 90 is neutral, and you define safe. Whatever the two numbers mean on your machine, 90 is the resting value. Limp is right for a desk toy, braking is right for wheels, and a loaded joint that goes limp falls.
5. Clamp on your side too. The app keeps gestures and held poses inside your declared band, but walks, spins and wheel drives can go past it. Refuse anything that would hurt the machine.
6. Go safe on disconnect. Link dies, process exits, Ctrl-C: release or brake on the way out. A body that holds its last command after the app is gone will burn something.
7. Power from the drive rail, common ground. Never off a logic pin. Two hobby servos alone can pull about 2A between them.
8. Interpolate. Moves look alive when the body glides between keyframes at about 50Hz. Snapping works and looks like a robot from 1985.

Code you can steal

• relay_chip.py is the stock chip software, the one the build page's USB installer puts on kits. MicroPython on a Pico, but the wire half (ws_open, hello_msg, the serve loop) is plain protocol work, and it only touches motors through two functions, board.servoWrite and board.release. It also has what the toy above skips: link and relay heartbeats, re-dial, watchdog, self heal. growbot-body-kit.zip carries the same file.
• arm_body.py drives a servo arm on the Pico's spare sockets from {"t":"arm"} frames, with clamps, a speed limit and an idle let-go. Optional: see Add an arm.
• act_engine.py is the keyframe glide engine: 147 lines, no MicroPython imports, every platform bit passed in. It runs unchanged on CPython. Use it instead of writing your own easing.
• ESP32 runs the same program on a different board; its page installs the copy from the kit.
• growbot-v0-bridge.zip makes a Raspberry Pi with serial bus servos (Pi Zero, SCS0009) a body for the phone app; the brain still runs on the phone. It has the websocket client, a servo adapter over the vendor's own bus driver, a calibration wizard that reads the servos back, and a mock test you can run with no hardware. A community builder has run it on a real V0. Tell us what happens on yours.
• growbot-v0-alive.zip runs the creature itself on a V0 Pi, no phone: the same mind as the app (its prompts and soul, byte for byte) thinks through growbot.dev, and the Pi's own body code drives the two legs, the MPU-6050, the speaker, the mic and the camera. It feels taps, shakes and falls, hears you, looks when something happens (the camera is on by default; type /eyes off or set camera.enabled to false in body.v0.json to turn it off), talks, gestures, remembers and dreams, and takes a few short steps forward or back with the old walk policy (rough on 64 mm legs, never a spin). A stance check and the motion sense calibration come with it, and its tests run on a laptop with no hardware. Start with its README.
• The public repo has an older copy of the chip software, the automower port above, the trained walk policy with its weights, and agent-harness/, a separate brain loop and body adapter reference.
• SPEC-BODY-TRUTH.md describes a body in general: each motor's range, rest point, direction and trim. Worth a read even if you never run the harness.

Two files in the kit will send you the wrong way

Connection limits

• No authentication. Whoever holds the pairing code can drive the machine, impersonate it (which disconnects the real body) or read its connection log at /d/<code>/log. Treat the code like a password and keep it out of public posts.
• Use a different code for each body. A new hello replaces the previous body connection, and the relay closes the old one with code 4001. Bodies that keep reconnecting over each other can end up sharing one code.
• Say hello first. If your first frame is not hello or attach, the relay replies {"t":"err"} and ignores you until you send one.

back to the app · driving a stock robot with your own brain instead: agent-docs · built something? drop a note in Discord