Build it, stage by stage

Objective. A rig that can fall over in exactly one plane, with a motor and flywheel at the top. No cube. No CAD. You are building a test bench, not a product, and it should look like it.

Why a flywheel can hold anything up

Get this in your bones before cutting anything. There is no outside force available — the cube cannot push on the air. All it can do is move momentum around inside itself. Spin the wheel one way and the body must rotate the other way, because the total has to stay put. The figure below has gravity switched off so the bookkeeping is visible: the blue bar is the sum, and it never moves.

Parts

• Gimbal BLDC motor, driver, magnetic encoder, IMU, microcontroller, bench supply or LiPo — see the stacks page for four costed options.
• One 608 bearing (skateboard bearing, 8 mm bore) and an 8 mm shaft or bolt.
• An arm: 150–200 mm of aluminium extrusion, plywood, or a printed beam. Stiff beats light.
• A base with real mass — 2 kg minimum, or a G-clamp to the bench.

Steps

1. Press the 608 bearing into the base and fit the shaft. The arm pivots on this and nothing else.
2. Bolt the motor at the top of the arm with its shaft parallel to the pivot axis. Out by 10° and a chunk of your torque goes into twisting the rig instead of correcting the lean.
3. Fit the flywheel. For now, anything round with mass at the rim — a printed disc with bolts through it is ideal because you can add and remove inertia later.
4. Clamp the base down. If the base can rock, you are building a two-body problem you did not intend to solve.
5. Route motor wires along the arm and down through the pivot axis, not out sideways. A wire loop that stretches as the arm tilts is a spring you will spend a day chasing.

Objective. An angle you trust, at your real loop rate, with the motor physically disconnected. Most "my cube oscillates" problems are stage-2 problems that were never tested.

You have two sensors and both lie, in different directions. The accelerometer tells you which way gravity is — true on average, buried in noise, and corrupted by any real acceleration. The gyroscope tells you how fast you are rotating — smooth and clean, with a small bias that integrates into a steadily growing error. Blend them: trust the gyro over short times, let the accelerometer slowly pull the estimate back.

// once per control tick, dt seconds apart
float accAngle = atan2f(ax, ay) * 57.2958f;      // degrees, check YOUR axes
tilt = (1.0f - ALPHA) * (tilt + gyroZ * dt) + ALPHA * accAngle;
// ALPHA around 0.02 at 500 Hz. Smaller = trust the gyro more.

Steps

1. Wire the IMU on SPI, not I2C. At 500 Hz with three sensors you run out of I2C bus before you run out of CPU.
2. Mount the IMU close to the pivot axis. An accelerometer far out on a rotating arm reads centripetal and tangential acceleration on top of gravity, and you cannot filter that away — it is real signal from the wrong thing.
3. Print raw accelerometer and gyro values and confirm the signs. Tilt the arm right, decide which way is positive, write it down. Half of all first-attempt sign errors live here.
4. Measure gyro bias: hold perfectly still for 10 s, average the reading, subtract it forever after.
5. Implement the filter and log to a ring buffer in RAM, dumping after the run. Printing inside the control loop adds milliseconds of jitter and will itself destabilise the cube.

Objective. Prove that when you ask for 0.05 N·m you get 0.05 N·m. The controller's output is a torque; if your driver only does voltage or speed, every stage after this is built on sand.

The measurement that settles it

Do not trust the library's word for it. Clamp the arm so it cannot move, command a step of torque, and record the wheel's speed from the encoder. The wheel's angular acceleration times its inertia is the delivered torque:

tau_delivered = J_wheel × (dω/dt)

Command 25%, 50% and 100% of your intended maximum and plot delivered against commanded. You want a straight line through the origin. A flat spot near zero is motor deadzone — identify it now and compensate, or the controller spends its life fighting an invisible nonlinearity. A curve that flattens at the top means you hit a current limit earlier than you thought.

Why the top end sags

Available torque falls as the wheel speeds up, because back-EMF eats the voltage headroom. This is not a detail; it is the reason cubes fall over. Watch the operating point walk out along the envelope during a real catch:

1. Confirm your driver does current sensing. If not, you are in voltage mode — note it and expect softer disturbance rejection.
2. Clamp the arm rigidly. It must not move at all during this stage.
3. Run FOC calibration: pole pairs, encoder zero offset, phase order. If the motor locks or stutters at startup, swap two phase wires.
4. Plot delivered vs commanded torque at 25/50/100%. Record the deadzone threshold.
5. Reverse test: spin the wheel up, command opposite torque, confirm it brakes at the rate you asked for. Bidirectional authority is the whole game.

Objective. Four numbers measured off your actual rig, put into the simulator, giving you three gains and — more importantly — a verdict on whether your motor is big enough, before you tune anything.

Measuring the four numbers

The bifilar trick is worth ten minutes. Flywheel inertia is the number the whole design hinges on, and a printed wheel with bolts in it is nothing like the uniform disc a CAD mass-properties dialog assumes.

1. Measure M, l, J_p and J_w. Write them on the rig with a marker.
2. Put them into the simulator and read off the gains, the fall time constant and the max recoverable lean.
3. Set your control rate to roughly 30× faster than the fall time constant — the ratio ETH used when they picked 20 ms for their 1‑DOF prototype. On a 107 ms time constant that lands near 300 Hz.
4. Add your measured IMU noise and loop latency in the simulator and check recoverable lean again. That is the honest number.

Objective. It balances. Three gains, applied in a specific order, with safety cutoffs written before the control law.

The failure that kills most first builds

Leave out the wheel-speed term and your cube balances beautifully for four seconds and then drops. The wheel winds up one way, reaches no-load speed, has no torque left, and that is that. With the term in, the controller deliberately leans a fraction to bleed the wheel back toward zero — trading a little tilt for momentum headroom. Both cubes below are identical and get identical kicks; the left has that one gain deleted.

Order of tuning

1. Safety first. Tilt past 20°, wheel speed past 90% of no-load, or a missed control tick — cut the motor. Write this before the control law, because you need it in the first thirty seconds.
2. K_θ alone, raised until the rig fights back and then oscillates. Note where oscillation starts.
3. K_θ̇ raised until that oscillation damps. Too much and it goes sluggish and noise-sensitive.
4. K_ω last, and never zero. Start at the simulator's value; raise it until the wheel reliably returns toward zero within a few seconds of a disturbance.

Firmware skeleton

Structure matters more than the exact API — fixed-rate task, filter, state feedback, saturate, safety. The motor calls are whatever your driver library uses.

// ---- gains straight from the simulator ----
const float K_TH = 49.37f;     // tilt        (N.m per rad)
const float K_TD = 5.35f;      // tilt rate   (N.m per rad/s)
const float K_W  = 0.0268f;    // wheel speed (N.m per rad/s)
const float ALPHA = 0.02f;     // complementary filter
const float DT = 1.0f / 500.0f;
const float TILT_LIMIT = 20.0f * DEG2RAD;
const float W_LIMIT = 0.90f * W_NOLOAD;
const float TAU_MAX = 0.18f;

float tilt = 0, tiltRate = 0, biasInt = 0;

void controlTick() {              // from a hardware timer, NOT loop()
  imu.read();
  tiltRate = imu.gyroZ - gyroBias;
  float accAngle = atan2f(imu.ax, imu.ay);
  tilt = (1.0f - ALPHA) * (tilt + tiltRate * DT) + ALPHA * accAngle;

  float w = motor.shaftVelocity();          // rad/s, relative to the body

  // ETH's trick: absorb constant sensor bias into a filter state instead
  // of letting it park the wheel at a non-zero speed forever.
  biasInt += 0.02f * tilt * DT;
  float tiltCorrected = tilt - biasInt;

  if (fabsf(tilt) > TILT_LIMIT || fabsf(w) > W_LIMIT) { motor.disable(); return; }

  float tau = K_TH * tiltCorrected + K_TD * tiltRate + K_W * w;
  tau = constrain(tau, -TAU_MAX, TAU_MAX);
  motor.move(tau);                          // TORQUE mode, not voltage

  logRing[logIdx++ & LOG_MASK] = { tilt, w, tau };  // dump later, never print here
}

The biasInt term is worth understanding rather than copying. A constant offset in your tilt estimate — a millimetre of IMU misalignment — looks to the controller like a permanent lean, so it holds permanent torque, so the wheel accelerates forever. ETH's published trace shows an uncorrected 0.058 rad offset parking the wheel at 37 rad/s indefinitely. The low-pass integrator soaks that into a filter state instead.

1. Write the safety cutoffs and test them by hand before enabling the control law.
2. Run the control law from a hardware timer or a pinned RTOS task — never from loop() with delay().
3. Tune K_θ, then K_θ̇, then K_ω, in that order.
4. Add the bias integrator and confirm the wheel settles toward zero rather than parking at a constant drift.
5. Dump the ring buffer after a fall and actually read it. The last 200 ms tell you whether you ran out of torque, ran out of wheel speed, or lost the angle.

Objective. Remove the mechanical problems that would otherwise be multiplied by three. The big one is flywheel balance, and it has a quantitative test most people skip.

Balancing the flywheel, with a number

An unbalanced wheel shakes the frame and your IMU reads that shake as tilt. You do not need a balancing machine — you already have an accelerometer bolted to the thing:

1. Clamp the rig. Spin the wheel to a steady 1500 rpm under control.
2. Log accelerometer magnitude for 5 seconds; record peak-to-peak.
3. Stop, mark the wheel at 12 o'clock, add a small mass (tape, a nut) at one position, repeat.
4. Work around the wheel until you find the position that reduces vibration, then refine the amount.

Target: vibration at 1500 rpm small compared to the tilt signal you are trying to measure. In practice, under about 0.05 g peak-to-peak and the control loop stops caring.

1. Balance the flywheel; log the before and after vibration numbers.
2. Check hub-to-shaft perpendicularity — spin it and watch the rim edge-on for wobble. Willem Pennings' cube needed paper shims to correct a bore that was not square to the wheel face.
3. Confirm rim mass really is at the rim. Inertia goes as radius squared, so mass at 80% radius is worth 64% of the same mass at the edge.
4. Verify there is no gearbox anywhere in the drive. Backlash puts a discontinuity in the middle of your feedback path.
5. Re-run the stage-3 torque test after any mechanical change — friction changes move your torque budget.

Objective. The same controller, now inside a cube standing on one edge. The plant has changed, so you measure it again — a real cube with motors bolted to its faces is nothing like the uniform solid a simulator assumes.

Dimensioned drawings for frame, flywheel, motor mount and pivot are generated from your cube size on the blueprints page — including how many bolts to put in the wheel to reach the inertia the physics actually asks for.

Geometry worth knowing before you cut

Balanced on an edge, the centre of mass sits a/√2 above the pivot — for a 120 mm cube, 84.9 mm. That is your lever arm, and required torque scales with it and with mass, which is why doubling cube size costs far more than double the motor.

1. Build the frame. Stiffness matters more than lightness, within reason — flex between IMU and pivot reads as phantom tilt. But ETH also note the housing must stay light, because mass costs recovery angle directly.
2. Harden the pivot edge: steel ball, brass insert, or a dedicated bearing. Printed plastic creeps under concentrated load and your geometry quietly changes.
3. Design in ballast points — screw bosses for trim weights. You will need them in stage 8 and retrofitting them is miserable.
4. Re-measure M, l and J_p for the assembled cube and re-run the simulator. Expect different gains.
5. Route power and signal so nothing crosses the pivot and nothing flaps.

Objective. Corner balancing. Three wheels, spin axes along the three cube edges meeting at the balancing corner, each wheel plane ideally passing through the centre of mass.

Centre of mass becomes a first-class problem

For corner balancing the CoM must sit on the body diagonal, and you will not hit that by luck. Both ETH and the HTL Hollabrunn team independently flag that at an unstable equilibrium, small CoM offsets create outsized tipping moments. Find it empirically: suspend the cube from one corner on a thread and mark the vertical line on the body; repeat from a second corner. The lines intersect at the CoM. Add trim mass until that point lands on the diagonal.

1. Get all three axes balancing independently on their edges before attempting a corner. Three working single-axis loops is a milestone; three broken ones is undebuggable.
2. Find the CoM by the two-suspension method and trim it onto the body diagonal.
3. Move to a proper 3D attitude estimate — the three edge-tilt angles are no longer independent once you stand on a corner.
4. Build the coordinator link: torque setpoints out, wheel speeds back, at control rate, with a timeout that disables motors if a node goes quiet.
5. Bring up one axis at a time on the corner with the other two disabled and the cube hand-supported.

Objective. Get from lying flat to balancing on a corner without being placed there. Spin a wheel up, brake it hard, and the momentum transfer flips the cube.

ETH used an RC servo slamming a metal barrier into a bolt head on the wheel — a mechanical brake, not an electrical one. Shorting the motor phases is the cheap electrical version; it transfers momentum more slowly, so you need a bigger wheel or a faster spin for the same impulse. Their first design used a solenoid and was dropped for being 39 g heavier.

1. Compute the momentum needed for a 45° flip from rest and check your wheel can store it at a speed your motor actually reaches.
2. Build the brake. Mechanical is more violent and more effective; phase-shorting is free and gentler.
3. Test the flip with the balance controller disabled and the cube on a soft surface. It will land badly many times.
4. Add the catch: hand over to the balance controller the moment tilt enters its valid range.
5. Reinforce the impact corner. Repeated hard landings on one printed corner is a losing fight.

One pattern visible only in aggregate: most public "Cubli" repositories are short-lived student projects with a handful of commits and no documented successful balance. The ones that worked published their full parameter set or their actual gains. Treat an undocumented build as unverified, however good the video looks.