Docs

Interrupts: the board counts a pin's edges

A pulse from a wheel sensor is over in a millisecond. A program that looks at the pin now and then misses most of them, and one that looks all the time does nothing else. An interrupt has the chip notice each edge by itself. In Zeno the board counts them, and the program asks for the count.

from board import input_pin, pin, rising

let sensor = input_pin(3)
let turns = sensor.interrupt(rising)

pin(3).on()                # on a computer the program plays the sensor
pin(3).off()
pin(3).on()

print(turns.edges())       # 2
print(turns.edges())       # 0: they were taken

The reasons for each choice are in chapter 50 of decisions.md. The example examples/tachometer.zeno counts the turns of a wheel in each stretch of time.

The rule

The program's own code never runs inside an interrupt. The board counts what happened, and the program asks when it chooses to. No function starts by itself in the middle of another, so no variable is shared with one, and there is no volatile, no critical section and no race to find.

What an interrupt has

Write Gives
button.interrupt(falling) the edges of that input pin, counted from now on: an Interrupt
press.wait() waits for an edge, then gives how many have come since the program last took them
press.edges() the same count without waiting: 0 when none has come
press.number which pin it is

The edge is rising (low to high), falling (high to low) or either, from the board module. They are values of the type Edge, and a str in their place is refused:

error: an interrupt counts `rising`, `falling` or `either` edges, from the `board` module, and this is str

The pin is still an input. button.is_low() reads it as before (inputs.md). One pin has one interrupt: a second interrupt( ) on it starts the count again, with the new edge.

Three ways to use one

Nothing else to do waits. On a board the chip sleeps until the edge:

from board import falling, input_pin, led, pin, pull_up

let button = input_pin(2, pull_up)
let press = button.interrupt(falling)

pin(2).off()               # stands in for a finger, on a computer

press.wait()
led.toggle()

A loop that does other things asks, and loses nothing however long a round takes:

from board import falling, input_pin, pin
from time import sleep

let press = input_pin(2).interrupt(falling)
pin(2).on()
var presses = 0
for round in range(3) {
    pin(2).toggle()
    presses += press.edges()
    sleep(1 ms)
}
print(presses)

A rate is a count taken at each tick of a ticker (ticker.md):

from board import input_pin, pin, rising, ticker

let turns = input_pin(3).interrupt(rising)
let second = ticker(10 ms)
pin(3).on()
second.wait()
print(turns.edges(), "turns in this stretch")

A button bounces: one press can be several edges within a few milliseconds. A program that wants presses takes the count, sleeps 20 ms, and takes it again to throw the bounces away.

What is refused while the program runs

Each is a ValueError:

The program The message
a pin with no interrupt pin 7 of this board cannot count its edges
press.wait() on a computer, with no edge counted the board says no edge can ever come on pin 2, so the program would wait for ever. On a computer nothing is wired to a pin: drive it with `pin(2)` before the wait

On a computer

Nothing is wired to the simulated board. The edges it counts are the ones the program drives on that pin itself, with pin(2).on() and off(), as if a wire joined the two. Nothing can drive a pin while the program waits, so a wait() with nothing counted would never end, and is an error instead.

On a board

The board header has three functions (board.md):

/* Count the pin's edges from now on: 1 rising, 2 falling, 3 either.
 * False if this pin has no interrupt. */
static bool zeno_board_interrupt(int pin, int edge);
/* How many were counted since this was last asked. Start again from none. */
static int zeno_board_edges(int pin);
/* The same, after waiting until at least one has come. */
static int zeno_board_edges_wait(int pin);

The chip's own handler is where the counting is done, and it is two lines. For an STM32 with ST's HAL the whole of it could be (a sketch, not tried on hardware):

static volatile int my_edges[16];

void HAL_GPIO_EXTI_Callback(uint16_t line) {        /* the chip calls this at each edge */
    my_edges[__builtin_ctz(line)]++;
}

static int zeno_board_edges(int pin) {
    __disable_irq();
    int edges = my_edges[pin];
    my_edges[pin] = 0;
    __enable_irq();
    return edges;
}

static int zeno_board_edges_wait(int pin) {
    for (;;) {
        __disable_irq();
        int edges = my_edges[pin];
        my_edges[pin] = 0;
        if (edges == 0) __WFI();                    /* sleep; an edge that is pending wakes it at once */
        __enable_irq();
        if (edges > 0) return edges;
    }
}

Looking at the count and going to sleep is one step there, with the interrupts off, so an edge between the two is not slept through. That is why the wait belongs to the board. Only a program with an interrupt calls these three.

In a built program

An interrupt is the pin's number, an int64_t. press.edges() is one call, zeno_interrupt_edges(2).

Not yet

A function of the program run at each edge, waiting for the first of several interrupts and tickers, the time an edge came, and debouncing in the board. No interrupt has run on a real board. See 50.6 in decisions.md.

This page is docs/interrupts.md in the language repository.