Talking to Hardware

Programming for Robotics 1 section 7 drew a seam: the robot logic calls three methods (range_m, ticks, set_duty) and anything that provides them can be plugged in. It tested everything against fakes and left the real class as a short sketch. This chapter fills the seam in. It covers the six ways a processor talks to the world (digital pins, PWM, the ADC, I2C, SPI and UART), what each is for, how fast it is, how it is wired, and how to write the code on both sides of the wire: a driver that turns bytes into physical units, and a fake bus that lets the driver be tested on an ordinary PC before any wire is connected. It ends with the real PicoHardware for the build robot of Robotics Fundamentals 10 section 9, assembled from pieces that were tested.

As in Programming for Robotics 1, the blocks build on each other like one growing file: later blocks use names that earlier blocks define.

1. Six ways to talk to the world

Basic Electronics 10 section 1 listed what a board offers: pins that can be a digital input, a digital output, an analogue input, a PWM output, or a special function (serial, I2C, SPI). The program sees each as a different kind of object, with a different cost in wires, time and code:

The choice is usually made for you by the part: the chip comes with an I2C or SPI or serial interface and you use what it has. What you control is the speed, the wiring and the code. Before looking at each, here is the time it takes to move 12 bytes (an IMU's six 16-bit values) over each. The formulas are explained in sections 4 and 5; the functions are used again in section 12.

The same 12 bytes take 10 microseconds or 12.5 milliseconds depending on the bus. Against a 20 ms loop, the slow serial link alone uses 62.5 % of the period (12.5 / 20), and a blocking read of it would stall the loop for that long (Programming for Robotics 1 section 5). The speed of a bus is a budget item, exactly like the stages of Programming for Robotics 1 section 12.

2. Pins: digital I/O, the ADC and PWM

On a Raspberry Pi Pico running MicroPython, a pin is an object from the machine module. The block below shows the four things you do with pins all the time. It is written from memory of the MicroPython documentation and has not been run on a board; the pin numbers (GP numbers, not physical pin numbers) are those of the build robot, which section 10 lists in full.

The ADC: counts to volts

The Pico's ADC is 12 bits (Basic Electronics 10 section 4), but MicroPython's read_u16() returns a number scaled to 16 bits so that code does not change between boards. The scaling is from memory: the 12-bit code is shifted up by four places (a multiplication by 16), so the lowest four bits carry no information. To convert, divide by 65535 and multiply by the reference voltage, then undo any voltage divider in front of the pin.

PWM: duty to a motor command

PWM is set by a frequency and a duty cycle (Basic Electronics 10 section 5). On the Pico, duty_u16 takes the duty as a 16-bit number, whatever the counter really has. Two decisions are the program's: the frequency and the mapping from a command to a duty.

• Frequency. A 125 MHz clock and a 20 kHz carrier leave 125 000 000 / 20 000 = 6250 steps per period (Basic Electronics 10 section 5), about 12.6 bits: ample for a motor. Below about 15 kHz the motor whines; far above 20 kHz the driver loses energy switching. A Pico has one frequency per PWM slice, and each slice serves two pins (section 10), so both motor pins of the build robot are on one slice and share the 20 kHz.
• Deadband. A small motor does not turn below about 18 % duty (Basic Electronics 9 section 2), so a command of 5 % would only heat it. The mapping sends the smallest meaningful command to the first duty that moves the wheel, spreads the rest linearly up to 100 %, and sends tiny commands to zero.

Now the motor as an object. A TB6612-style driver (the example of Robotics Fundamentals 10 section 9.2) takes two direction inputs and one PWM input per motor. MotorChannel does not import machine: it is given its pins, so the same class runs on a Pico or against the fake pins below. (The truth table in the comments, including that both-low coasts and both-high brakes, is from memory of the TB6612FNG datasheet: check the datasheet of your module.)

Note the order inside MotorChannel.__init__: the PWM frequency is set, then the motor is told to stop. A motor driver must never be left with an undefined input, so the safe state is the first thing the constructor establishes (Basic Electronics 10 section 1: pins float at power-on, which is why the build robot's standby pin has a pull-down resistor).

3. The Raspberry Pi is different

A Raspberry Pi (Basic Electronics 10 section 9) is a computer running Linux, not a bare board. Its pins are the same kind of thing (3.3 V logic, not 5 V tolerant: Basic Electronics 10 section 1), but three things change. There is no analogue input: an ADC chip is added over I2C or SPI (Basic Electronics 7). The pin numbers are the Broadcom (BCM) numbers, not the Pico's GP numbers. And the operating system can pause your program for milliseconds at any moment, so timing that a Pico does in hardware (counting encoder edges, measuring a 1 ms echo) is far less reliable (Basic Electronics 10 section 6 advised a Pico or Arduino beside the Pi for fast encoders).

The usual Python library is gpiozero, which gives each device its own class. This sketch is from memory of its documentation, has not been run on a Pi, and uses arbitrary BCM pin numbers, not the build robot's map:

The same two jobs are easier on a Pi in one way and harder in another. Easier: libraries exist for almost everything, and you can plot, log to disk and use a full network. Harder: the DistanceSensor times its echo in software on a non-real-time system, so its readings can jitter by more than a Pico's; PWM is often generated in software (jittery) unless a hardware-timed backend is selected (from memory: gpiozero can use the pigpio library for that). For a robot that must keep a 50 Hz loop, a common design is a Pico or Arduino doing the fast, timing-critical work and a Pi doing the planning (Programming for Robotics 9, planned and not yet written), joined by UART or USB serial (section 5).

4. I2C: two wires, many devices

I2C (“eye-squared-C”) joins a host and several devices on two shared wires: SDA (data) and SCL (clock). The host drives the clock; every transfer starts with the address of the device it wants, and only that device answers. Both wires are open-drain (Basic Electronics 8 section 5): a chip can only pull a wire low, and a pull-up resistor to the supply makes it high again, which is why the bus needs two resistors and why two devices can never fight over it.

Speed, address and the cost of a transaction

The standard clock speeds are 100 kHz (standard mode), 400 kHz (fast mode) and 1 MHz (fast-mode plus). Every byte on the wire is 9 bit times: eight data bits plus one acknowledge (ACK) bit, in which the receiver pulls SDA low to say “got it”. To read from a register, the host sends the device address with the write bit, the register number, a repeated START, the address again with the read bit, and then clocks in the data bytes. That is 2 + 1 + n bytes for n data bytes, which is what i2c_bits in section 1 counted. The start of such a transaction looks like this (the first byte of the example below is address 0x68 with the write bit; one character column is a quarter of a bit time; the data wire changes while the clock is low):

The pull-up resistors

Two limits fix the pull-up value, as in Basic Electronics 8 section 5. Too small, and a chip cannot pull the wire below a valid low (it can sink about 3 mA). Too large, and the wire, which has capacitance, rises too slowly for the clock speed. The I2C specification measures the rise time between 30 % and 70 % of the supply: t(rise) = 0.8473 × Rp × C, and allows 1000 ns in standard mode and 300 ns in fast mode.

I2C in MicroPython, and the clock-stretching and stuck-bus problems

MicroPython's I2C object has scan(), readfrom_mem(addr, reg, n) and writeto_mem(addr, reg, data), which are exactly the three calls that a register-based driver needs. This block is from memory and was not run on a board:

Two failures are specific to I2C. A device may stretch the clock (hold SCL low until it is ready), which makes a transaction take longer than the formula says. And a device that was reset in the middle of a byte can hold SDA low, which blocks the whole bus until it is released; the usual recovery, from memory, is to pulse SCL up to nine times as an ordinary output until SDA rises, then send a STOP. Both are reasons for the timeouts and retries of section 11.

5. SPI and UART

SPI: a clock, two data wires and a chip select

SPI uses three shared wires and one extra wire per device: SCK (clock from the host), MOSI (host out, device in), MISO (device out, host in) and CS (chip select, low while that device is being addressed; every other device ignores the bus). Data moves both ways at once, one bit per clock pulse, so a transfer of n bytes takes 8n / f seconds, with no address, no ACK and a clock that can be many megahertz.

UART: bytes with no clock, and the 8N1 frame

A UART sends bytes with no clock wire at all: the two ends agree beforehand on the baud rate (bits per second), and each byte is wrapped in a frame so the receiver can find it. The common setting is 8N1: 8 data bits, no parity, 1 stop bit. The line idles high; a byte begins with a start bit (low), then the data bits least significant bit first, then a stop bit (high). That is 10 bits for every 8 bits of data, so a byte takes 10 / baud seconds and the most the link can carry is baud / 10 bytes per second.

6. Libraries or your own driver?

A driver is the code that knows one chip: its address, its registers, its units. Most popular chips already have one, written by someone else. The decision is not “never write your own” or “always write your own”; it depends on what you need:

Writing a driver is smaller than it sounds: it is the datasheet's register map turned into a class of fifty lines. The rules that make it a good driver are the ones the rest of this chapter follows: take the bus as an argument (so a fake can replace it), check the chip's identity at start-up, read related values in one burst so they describe the same instant, convert to SI units inside the driver, raise an OSError when the bus fails (never return a fake zero), and keep the constants from the datasheet next to the code that uses them.

7. Reading a datasheet register map

A register-based chip is a small block of memory that you read and write by address. The datasheet's register map tells you what each address holds. Below is the map of an invented six-axis IMU modelled on common chips (the gyroscope and accelerometer of Robotics Fundamentals 6 section 4), so that the example is complete and can be tested. The things to find in any real datasheet are the same: the device address, an identity register, the configuration register and what its bits mean, how to wake the chip, where the data is, in which byte order, and how many LSB make one physical unit.

The device address is 0x68 (7-bit; 0x69 if the address pin is high). The sensitivity is given in LSB per unit, one value per range setting: gyroscope 131, 65.5, 32.8 and 16.4 LSB per degree/s for the four ranges, accelerometer 16 384, 8192, 4096 and 2048 LSB per g. (Robotics Fundamentals 6 section 4 quotes the first of each: 131 and 16 384.)

From two bytes to a physical value

A fake bus, a fake chip and a driver

The fake bus has the same three methods as MicroPython's I2C. Devices are plain objects with read(reg) and write(reg, value). The fake IMU holds true physical values and works out the register bytes from them, so it checks the driver in the direction that matters: physical value in, bytes on the bus, physical value out. (A fake is only as right as your reading of the datasheet. It tests your code, not your understanding of the chip: the first run on real hardware is still the final test.) The bus can also be told to fail on demand, which no real bus does politely.

Now the driver itself. It takes the bus as an argument, checks WHO_AM_I, writes the configuration, wakes the chip, and reads all twelve data bytes in one burst (so the six values describe the same instant, and the transaction costs one address overhead instead of six). The scale tables are the datasheet's, written once at the top.

Read the output as the formulas above predict: 10 dps is 1310.72 counts, which the chip can only store as 1311; 1311 / 131 = 10.008, an error of 0.008 dps, most of it (0.0055) from the datasheet's rounded 131 and the rest (0.002) from rounding to whole counts. The 0.5 dps is a few counts (66 of them), so it is only good to about a percent. A 300 dps spin on the ±250 range saturates and reads about 250, which is why the range must match the robot (a robot that turns at 3 rad/s, 172 dps, fits in ±250 with margin; one spun by hand might not). The wider range reads 299.70 with a coarser step.

The two quick checks on the byte handling, which are the two classic driver bugs (the wrong byte order and the missing sign step), run in a few lines:

The same driver on a Raspberry Pi

On a Pi the I2C library is usually smbus2, whose method names (from memory) differ from MicroPython's: read_i2c_block_data(addr, reg, n) returns a list, and write_i2c_block_data(addr, reg, list) takes one. A ten-line adapter gives it the MicroPython names, so the Imu class above runs unchanged. The check below uses a fake with smbus2's method names (also from memory) wrapped around the fake bus, so it tests the adapter's list and bytes handling, not the library.

8. The ultrasonic sensor: pulse width to distance, with a timeout

The HC-SR04 style sensor (Robotics Fundamentals 5 section 3, wired in Robotics Fundamentals 10 section 9.5) is read by timing a pulse: a 10 microsecond high pulse on the trigger pin makes it send a burst of sound, and its echo pin then goes high for as long as the sound took to go out and come back. The pulse width gives the distance, and a missing echo gives a timeout, which must become “no reading” (None), not a wrong number (Programming for Robotics 1 section 11).

The class below takes its trigger pin, echo pin, a function that times a pulse (machine.time_pulse_us on a Pico, a fake in a test) and a microsecond sleep. On MicroPython, time_pulse_us(pin, 1, timeout_us) returns the width in microseconds, or a negative number on a timeout (from memory: −2 if the pulse never started, −1 if it never ended).

The 100 microsecond echo is 17 mm, under the 20 mm minimum, so it is rejected; the two negative values are the timeout cases. This version blocks for up to 25 ms inside pulse_us, which is the problem Programming for Robotics 1 section 5 identified (the loop cannot hold 50 Hz). The cure it described is a start-then-collect pattern: trigger now, return at once, and let the echo pin's edge interrupt record the times. The class below is the logic of that, with no hardware in it: the interrupt handler calls on_edge, the main loop calls poll once per pass and gets None until the answer is ready, then the width once, or −1 for a timeout.

On a real board, on_edge is called from a pin interrupt that reads time.ticks_us(), and the subtraction now_us - self.started_us must use ticks_diff (Programming for Robotics 1 section 3: the tick counters wrap). The timing diagram and the MicroPython glue are in PicoHardware (section 10), where the blocking version is used first because it is simplest, and replacing it with this one is a change inside that class only.

9. Wheel encoders with interrupts

An encoder pulse train must not be polled by a 50 Hz loop: at 0.3 m/s the build robot's wheel makes about 881 edges per second, one every 1.1 ms, and a 20 ms pass would see seventeen or eighteen of them at once and know nothing about their order. The edge must be handled when it happens, by an interrupt (Basic Electronics 10 section 6), and the loop reads a counter. The decoding rule is the state table of Robotics Fundamentals 6 section 2: the two channels A and B form a two-bit state that steps through four values in a fixed order, forwards or backwards; each step is one count; a jump of two states means an edge was missed.

The counts follow the table: twelve forward edges make +12, four reverse edges bring it to 8, and the impossible jump is counted as an error instead of guessed. A rising error count on a real robot means the interrupts are being missed (a handler too slow, a noisy wire, a wheel faster than the design), and it belongs in the log (Programming for Robotics 1 section 10).

The decoder is the same code on every board. Only the glue differs: the interrupt must read both pins and call step. In MicroPython that is pin.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=...) (from memory), and the handler is shown inside PicoHardware below. The 50 Hz loop reads the counter; since the interrupt can change it in the middle of a read, the read is done with interrupts briefly disabled (disable_irq and enable_irq in MicroPython, from memory: Basic Electronics 10 section 6 gave the same advice for 8-bit Arduinos).

10. The build robot's pin map and PicoHardware

The pins below are those of the wiring table of Robotics Fundamentals 10 section 9.5 (Pico GP numbers, an example from memory there: check your own pinout), plus one extension: an IMU on I2C bus 0, on GP0 and GP1, which that table leaves free. (GP0 and GP1 are the pins of I2C bus 0 and of UART 0 on the Pico, from memory: you may use the pair for one or the other.) The pin numbers in the sketch of Programming for Robotics 1 section 7 were only an example; this map replaces them.

Keeping the map as data in one place, and checking it for mistakes in code, catches the commonest wiring-plan error (one pin given two jobs) before anything is connected. The PWM slice of a Pico pin is (GP / 2) mod 8 and the channel is A for even pins and B for odd ones (from memory of the RP2040 design), so GP12 and GP13 are the two channels of slice 6: one frequency for both, which is why they were chosen together.

The free pins are few (GP8, GP22, GP27, GP28), and none of them forms a complete SPI or a second UART pair, so adding an SPI device means moving something (an expander for the line sensors, say). That is the real cost of a bus: pins. Now the class itself, the full PicoHardware for the three methods of Programming for Robotics 1 section 7, plus battery_v, line and start for later chapters. It is assembled from the tested pieces of this chapter (MotorChannel, Ultrasonic, QuadratureDecoder, Imu, check_devices from section 11, battery_v), and only the glue between them and the machine module is new and untested. It has not been run on a board; it is syntax-checked only.

Three points about it. Order: the outputs are set to their safe states first, before anything can go wrong later in the constructor, and standby (driver off) is the default. The seam held: Robot from Programming for Robotics 1 section 6 calls range_m(), ticks() and set_duty(left, right) and nothing else, so it does not change. What is still open: the blocking range read (replace it with the EchoTimer of section 8, inside this class), the motor ramp and the calibration of the deadband (Programming for Robotics 5), and all the timing behaviour on real silicon, which only a measurement with LoopStats (Programming for Robotics 1 section 2) can tell.

11. Bus errors, checksums, retries and the start-up scan

Real buses fail: a wire is brushed by a motor's noise, a connector works loose, a chip is not powered. The failure shows as an OSError from the library, a wrong byte, or silence. Four defences, each cheap, each testable on the fake bus.

A checksum: CRC-8, with a worked calculation

Where a link can corrupt data (serial links, long wires; many I2C sensors add a check byte), the sender adds a cyclic redundancy check, and the receiver recomputes it. A CRC-8 treats the bytes as one long binary number and divides it by a fixed polynomial, keeping the remainder. The bitwise version is short: put the byte into the running value, then for each of eight steps shift left, and whenever a 1 falls off the top, exclusive-or the polynomial in.

The two lines after the trace compare the function with published check values, written here from memory: the CRC-8 (polynomial 0x07) of the ASCII text 123456789 is the standard test value 0xF4, and the Sensirion-style CRC (polynomial 0x31, start 0xFF) of the bytes 0xBE, 0xEF is 0x92 in several Sensirion datasheets. The code agrees with both, which is a good sign for the function, though not a substitute for the datasheet of the chip you actually use. All 24 single-bit errors in the three-byte frame were caught.

Retries with a limit

A transient fault is often gone on the next try, so a read is retried; but a retry costs bus time, and an unlimited retry is a blocking wait in disguise. Give every retry loop a small limit, count the failures, and when the limit is reached report “no reading” (the stale-data rule of Programming for Robotics 1 section 11). The loop does not sleep between tries: it uses the pass structure of Programming for Robotics 1 section 5 if it needs to wait.

A scan at start-up

Before the loop starts, check that every chip the robot needs is there. A missing sensor found at start-up is a clear message; found in the middle of a run it is a stale reading and a stopped robot. The I2C scan() returns the 7-bit addresses that answered. The function below compares them with what the robot expects and also reports devices you did not plan for (a clue to a wiring or address mistake).

What happens when the check fails is a design decision made in advance: refuse to start and light the LED, or start in a degraded mode without that sensor (Programming for Robotics 7 and Programming for Robotics 12 return to degraded modes; both are planned and not yet written). For a sensor the robot cannot work without, refusing to start is the safe default.

12. Bus speed against the loop budget

Programming for Robotics 1 section 12 measured a pass in stages and kept the utilisation U = C / T under about 50 % on the worst pass. The bus is part of C. With the formula of section 4, t = 9 × (2 + 1 + n) / f, the cost of an added sensor is a calculation, not a guess.

The first rule of bus use follows: few, large transactions. One 12-byte burst costs 135 bits; six separate 2-byte reads would cost 6 × 45 = 270 bits, twice as much, with six chances to fail and six moments that are not the same instant. The second rule: never wait on a bus inside the loop without a limit (a stuck bus, section 4, would freeze the robot), which is why the retries of section 11 have a limit and the driver of section 7 raises an exception.

13. Challenges

Work these with a pencil and with Python. The solutions are text files with the working, and the code in them was run.

Next: Programming for Robotics 3, A Simulator to Test In

This chapter made the seam real: a PicoHardware built from tested drivers, a fake bus that let the driver be checked on a PC, and the arithmetic of what each bus costs in time. But the fakes of Programming for Robotics 1 and 2 only fake one wire at a time: a scripted list of ranges, a wall in one dimension. To test a line follower, an obstacle avoider or a planner, the “hardware” has to be a world: a robot that really drives around, whose wheels turn, whose range sensors see walls, and whose encoders and sensors have noise. Programming for Robotics 3 (planned; not yet written) builds that, a small two-dimensional differential-drive simulator in pure Python (using the kinematics of Robotics Fundamentals 4) that provides the same range_m, ticks and set_duty methods, so that every program in the rest of the course can be run, replayed and tested on any PC before it touches a motor.