GPIO API Reference

Overview

The brawl:device/gpio interface defines a minimal, hardware-agnostic GPIO API for WebAssembly (WASM) modules. It provides a consistent way to control and monitor digital and analog I/O across diverse embedded targets - ranging from microcontrollers to emulators - while remaining fully compatible with the WASM MVP specification.

Each function follows a simple convention: it returns a signed 32-bit integer, where negative values represent standardized error codes and non-negative values represent valid results or success indicators. This design keeps the ABI deterministic, low-overhead, and portable between environments, enabling WASM applications to interact directly with physical or virtual pins without callbacks, threads, or host-specific extensions.

Implementation Notes

This section outlines the expected behavior and conventions used by the brawl:device/gpio interface. It provides guidance for both host implementers and guest developers to ensure consistent behavior across WASM targets.

GPIO Enumeration

pinCount() returns the total number of GPIO-capable pins available on the target. pinList() populates a memory buffer with a list of available pin identifiers (uint8_t) in the host environment’s canonical order. Each pin identifier can be passed directly to pinOpen() to obtain a handle for further operations.

Interfacing With a GPIO Pin

Before reserving a pin, always call pinCapabilities() to verify that it supports the desired modes. Use pinOpen() to reserve the pin and obtain a handle; this handle is passed to all subsequent operations. When the pin is no longer needed, release it using pinClose(). Pins remain inactive and unpredictable until configured with either pinModeIn() or pinModeOut() to define their behavior and electrical characteristics.

Analog Measurements

pinAnalogRead() returns a value between 0 and (2^resolution) - 1, where the resolution is set using pinAnalogReadResolution(). pinAnalogWrite() accepts a value between 0 and (2^resolution) - 1, where the resolution is set using pinAnalogWriteResolution(). The returned value is proportional to the selected reference voltage (pinAnalogReference()).

Pulse Measurement

pinPulseIn() returns the duration of a pulse in microseconds (µs). Frequencies and PWM parameters are expressed in Hertz (Hz).

Interrupts (no callbacks)

When interrupts are available - they are polled, not event-driven. pinInterruptState() returns a GPIO_EDGE value when an edge has been detected and clears the latched state. Edges remain latched until pinInterruptState() is called. Changing the configured edge type using pinAttachInterrupt() automatically resets the latch.

Error Codes

All brawl:device/gpio functions return a signed 32-bit integer (int32_t), which encodes both result and error information:

Value
`ret < 0`	an error occurred.
`ret == 0`	operation completed successfully (or no value to return).
`ret > 0`	operation succeeded and returned a value (e.g., a pin level or handle).

Constants

GPIO Errors

All functions return a signed 32-bit integer (int32_t). If the value is negative, it represents an error code from the table below:

Constant
`GPIO_ERROR_BUSY`	The GPIO pin is already in use or reserved by another handle.
`GPIO_ERROR_UNSUPPORTED`	The requested operation or capability is not supported on this pin.
`GPIO_ERROR_TIMEOUT`	The operation did not complete within the expected time.
`GPIO_ERROR_INVALID_HANDLE`	The handle provided was invalid for the operation requested.
`GPIO_ERROR_INVALID_ARG`	The argument provided was invalid for the operation requested.

A return value >= 0 indicates success - either 0 for non-returning operations or a positive value for operations that produce a result.

GPIO Capabilities

Each GPIO pin can support one or more capabilities, reported by pinCapabilities(). These are bit-flags and may be combined using bitwise OR.

Constant (Flag)
`GPIO_CAPS_DIGITAL_IN`	Supports digital input.
`GPIO_CAPS_DIGITAL_OUT`	Supports digital output.
`GPIO_CAPS_ANALOG_IN`	Supports analog input.
`GPIO_CAPS_ANALOG_OUT`	Supports analog output.
`GPIO_CAPS_PULL_UP`	Internal pull-up resistor available (input mode).
`GPIO_CAPS_PULL_DOWN`	Internal pull-down resistor available (input mode).
`GPIO_CAPS_PUSH_PULL`	Push-pull output driver (actively drives both HIGH and LOW).
`GPIO_CAPS_OPEN_DRAIN`	Open-drain output (drives LOW, requires external pull-up for HIGH).
`GPIO_CAPS_PWM`	Supports pulse-width modulation or tone generation.
`GPIO_CAPS_IRQ_RISING`	Can trigger an interrupt on a LOW to HIGH edge.
`GPIO_CAPS_IRQ_FALLING`	Can trigger an interrupt on a HIGH to LOW edge.
`GPIO_CAPS_IRQ_CHANGE`	Can trigger an interrupt on any change (both edges).
`GPIO_CAPS_LED`	Pin is connected to an onboard or indicator LED.

Combine capability flags with the bitwise OR operator (|) to describe a pin that supports multiple features. Pins marked as GPIO_CAPS_LED typically drive an onboard indicator.

Digital State

Represents the logical level of a digital pin.

Constant
`GPIO_STATE_LOW`	Logic LOW / GND.
`GPIO_STATE_HIGH`	Logic HIGH / VCC (3V3 or 5V).

Digital Pull (Input)

Configures the internal resistor behavior when a pin is set as an input.

Constant
`GPIO_PULL_NONE`	No internal pull resistor (floating input).
`GPIO_PULL_UP`	Enables a weak internal pull-up resistor.
`GPIO_PULL_DOWN`	Enables a weak internal pull-down resistor.

Digital Drive (Output)

Selects how a digital output drives its line.

Constant
`GPIO_DRIVE_DEFAULT`	Use the platform’s default drive mode (typically push-pull).
`GPIO_DRIVE_PUSH_PULL`	Actively drives the line HIGH or LOW (standard output).
`GPIO_DRIVE_OPEN_DRAIN`	Only drives LOW; releases the line for external pull-up when HIGH.

When using GPIO_DRIVE_OPEN_DRAIN, writing LOW drives the line low, while writing HIGH releases it (requires a pull-up resistor).

Digital Interrupt Edge (Input)

Defines which signal transitions generate an interrupt event.

Constant
`GPIO_EDGE_NONE`	No interrupt triggered.
`GPIO_EDGE_RISING`	Trigger on LOW to HIGH transition.
`GPIO_EDGE_FALLING`	Trigger on HIGH to LOW transition.
`GPIO_EDGE_CHANGE`	Trigger on any change (both directions).

Interrupt edges are polled via pinInterruptState(), which returns a GPIO_EDGE and clears the latched state.

Bit Order

Specifies the bit transmission order for pinShiftIn() and pinShiftOut() operations.

Constant
`GPIO_MSBFIRST`	Most-significant bit first.
`GPIO_LSBFIRST`	Least-significant bit first.

Application Programming Interface (API)

//--------------------------------------------------------------------------
// brawl:device/gpio

// GPIO errors
enum GPIO_ERROR {
                         // >= 0              no error
  GPIO_ERROR_BUSY           = -1,          // GPIO pin is in use
  GPIO_ERROR_UNSUPPORTED    = -2,          // GPIO pin action unsupported
  GPIO_ERROR_TIMEOUT        = -3,          // GPIO pin operation timed out
  GPIO_ERROR_INVALID_HANDLE = -4,          // invalid handle
  GPIO_ERROR_INVALID_ARG    = -5           // invalid argument
};

// GPIO capabilities (flags)
enum GPIO_CAPS {
  GPIO_CAPS_DIGITAL_IN      = (1UL << 0),  // supports digitalRead()
  GPIO_CAPS_DIGITAL_OUT     = (1UL << 1),  // supports digitalWrite()
  GPIO_CAPS_ANALOG_IN       = (1UL << 2),  // supports analogRead()
  GPIO_CAPS_ANALOG_OUT      = (1UL << 3),  // supports analogWrite()
  GPIO_CAPS_PULL_UP         = (1UL << 4),  // DIGITAL IN: pull up
  GPIO_CAPS_PULL_DOWN       = (1UL << 5),  // DIGITAL IN: pull down
  GPIO_CAPS_PUSH_PULL       = (1UL << 6),  // DIGITAL OUT: push/pull between GND and VCC
  GPIO_CAPS_OPEN_DRAIN      = (1UL << 7),  // DIGITAL OUT: drives LOW, external resistor drives HIGH
  GPIO_CAPS_PWM             = (1UL << 8),  // supports pulse width modulation
  GPIO_CAPS_IRQ_RISING      = (1UL << 9),  // irq: on LOW   -> HIGH transition
  GPIO_CAPS_IRQ_FALLING     = (1UL << 10), // irq: on HIGH  -> LOW  transition
  GPIO_CAPS_IRQ_CHANGE      = (1UL << 11), // irq: on HIGH <-> LOW  transition
  GPIO_CAPS_LED             = (1UL << 12)  // pin is connected to an LED
};

// digital state
enum GPIO_STATE {
  GPIO_STATE_LOW            = 0,           // GND
  GPIO_STATE_HIGH           = 1            // VCC (3v3 or 5V)
};

// digital pull (input)
enum GPIO_PULL {
  GPIO_PULL_NONE            = 0,
  GPIO_PULL_UP              = 1,           // internal pull up
  GPIO_PULL_DOWN            = 2            // internal pull down
};

// digital drive (output)
enum GPIO_DRIVE {
  GPIO_DRIVE_DEFAULT        = 0,
  GPIO_DRIVE_PUSH_PULL      = 1,           // connected to either (GND or VCC)
  GPIO_DRIVE_OPEN_DRAIN     = 2            // drives LOW, external resistor drives HIGH
};

// digital interrupt edge (input)
enum GPIO_EDGE {
  GPIO_EDGE_NONE            = 0,
  GPIO_EDGE_RISING          = 1,           // trigger interrupt on change from LOW  -> HIGH
  GPIO_EDGE_FALLING         = 2,           // trigger interrupt on change from HIGH -> LOW
  GPIO_EDGE_CHANGE          = 3            // trigger interrupt on any change
};

// bit order
enum GPIO_BITORDER {
  GPIO_MSBFIRST             = 0,           // most significant bit first
  GPIO_LSBFIRST             = 1            // least significant bit first
};

Discovery and Mode

int32_t // GPIO_ERROR|int32_t
pinCount(void);

int32_t // GPIO_ERROR|int32_t
pinList(int32_t mem_ptr, int32_t max_items);

int32_t // GPIO_ERROR|GPIO_CAPS
pinCapabilities(int32_t pinNum);

int32_t // GPIO_ERROR|int32_t
pinOpen(int32_t pinNum);

int32_t // GPIO_ERROR|void
pinModeIn(int32_t handle, enum GPIO_PULL pull);

int32_t // GPIO_ERROR|void
pinModeOut(int32_t handle, enum GPIO_DRIVE drive);

int32_t // GPIO_ERROR|void
pinClose(int32_t handle);

Analog

int32_t // GPIO_ERROR|void
pinAnalogReadResolution(int32_t handle, int32_t bits);

int32_t // GPIO_ERROR|void
pinAnalogWriteResolution(int32_t handle, int32_t bits);

int32_t // GPIO_ERROR|int32_t
pinAnalogRead(int32_t handle);

int32_t // GPIO_ERROR|int32_t
pinAnalogReference(int32_t handle, int32_t mV);

int32_t // GPIO_ERROR|void
pinAnalogWrite(int32_t handle, int32_t value);

Digital

int32_t // GPIO_ERROR|GPIO_STATE
pinDigitalRead(int32_t handle);

int32_t // GPIO_ERROR|void
pinDigitalWrite(int32_t handle, enum GPIO_STATE state);

int32_t // GPIO_ERROR|void
pinAttachInterrupt(int32_t handle, enum GPIO_EDGE edge);

int32_t // GPIO_ERROR|void
pinDetachInterrupt(int32_t handle);

int32_t // GPIO_ERROR|GPIO_EDGE
pinInterruptState(int32_t handle);

PWM / bit-banging

int32_t // GPIO_ERROR|void
pinToneStart(int32_t handle, int32_t freq, int32_t duration);

int32_t // GPIO_ERROR|void
pinToneStop(int32_t handle);

int32_t // GPIO_ERROR|int32_t
pinPulseIn(int32_t handle, enum GPIO_STATE state, int32_t timeout_us);

int32_t // GPIO_ERROR|int32_t
pinShiftIn(int32_t handle_data, int32_t handle_clock, int32_t bit_count, enum GPIO_BITORDER bit_order);

int32_t // GPIO_ERROR|void
pinShiftOut(int32_t handle_data, int32_t handle_clock, int32_t bit_count, enum GPIO_BITORDER bit_order, int32_t value);

Example - LED Blink (C)

#include <stdint.h>
#include <stdio.h>

#include "brawl-device-gpio.h"

#define MAX_PINS 32

static void gpio_err(int32_t rc, const char *what) {
    if (rc < 0) fprintf(stderr, "%s failed: %d\n", what, rc);
}

int main(void) {

    int32_t n, rc;
    uint8_t ids[MAX_PINS];
    int32_t led_pin, led_h;
    int32_t caps;
    enum GPIO_DRIVE drive;

    // enumerate pins (WASM MVP: caller-allocated buffer)
    n = pinCount();
    if (n < 0) { gpio_err(n, "pinCount"); return 1; }
    if (n > MAX_PINS) n = MAX_PINS;

    rc = pinList((int32_t)(uintptr_t)ids, n);
    if (rc < 0) { gpio_err(rc, "pinList"); return 1; }

    // find a pin that supports LED
    led_pin = -1;
    for (int i = 0; i < rc; ++i) {
        caps = pinCapabilities(ids[i]);
        if (caps < 0) continue;

        // check the capabilities, break on first LED found
        if (caps & GPIO_CAPS_LED) { led_pin = ids[i]; break; }
    }

    // did we find an LED?
    if (led_pin >= 0) {

        // open and configure drive mode (prefer open drain if advertised)
        led_h = pinOpen(led_pin);
        if (led_h < 0) { gpio_err(led_h, "pinOpen"); return 1; }

        caps = pinCapabilities(led_pin);
        drive = (caps & GPIO_CAPS_OPEN_DRAIN) ? GPIO_DRIVE_OPEN_DRAIN : GPIO_DRIVE_PUSH_PULL;

        rc = pinModeOut(h, drive);
        if (rc < 0) { gpio_err(rc, "pinModeOut"); pinClose(led_h); return 1; }

        // this is where we do the business, toggle the pin repeatedly
        while (1)
        {
            // toggle the pin safely with a delay
            rc = pinDigitalWrite(led_h, GPIO_STATE_HIGH);
            if (rc < 0) gpio_err(rc, "pinDigitalWrite(GPIO_STATE_HIGH)");
            delay(250);

            // toggle the pin safely with a delay
            rc = pinDigitalWrite(led_h, GPIO_STATE_LOW);
            if (rc < 0) gpio_err(rc, "pinDigitalWrite(GPIO_STATE_LOW)");
            delay(250);
        }

        // close access to the pin (shouldn't get here)
        rc = pinClose(led_h);
        if (rc < 0) gpio_err(rc, "pinClose");
    }

    // if we get here, we couldn't find an LED
    return 1;
}

Revision

2025-10 (draft)