Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Status Code Reference

Every gallo_* FFI function (except the lifecycle calls gallo_init, gallo_init_with_serial_number, and gallo_free) returns a Status value. For C11/C17, cbindgen emits typedef int32_t Status together with integer constants, rather than making Status a true C enum type. To catch appended statuses at compile time, cast the scrutinee (switch ((enum Status)x)), omit any default: label inside the switch, and build with -Werror=switch. A post-switch fallback for an unknown numeric value is intentional and correct.

  • Ok (0) — success.
  • Negative values — errors, grouped roughly by peripheral.

Stability

Important

Status code numeric values are part of the C ABI and never change once shipped. Existing codes are never renumbered or reused; new codes are only appended at the bottom of the enum.

If you compile against a header from an older release, codes you don’t recognize will be values your code has never seen. Treat unknown negative values as “some error” — never assume a number that doesn’t appear in your header means success.

Complete Status Table

NameValueDescription
Ok0Operation successful
I2cReadFailed−1I²C read failed
I2cWriteFailed−2I²C write failed
InvalidResponse−3Firmware produced an invalid response
Uninitialized−4Library was not initialised (NULL context)
InvalidArgument−5Caller passed an invalid argument
PingFailed−6Ping round-trip failed
SpiReadFailed−7SPI read failed
SpiWriteFailed−8SPI write failed
SpiFlushFailed−9SPI flush failed
GpioGetFailed−10GPIO get failed
GpioPutFailed−11GPIO put failed
GpioWaitFailed−12GPIO wait failed
SetConfigFailed−13Set config failed (legacy)
VersionFailed−14Version query failed
I2cWriteReadFailed−15I²C write-read failed
I2cSetConfigFailed−16I²C set config failed
SpiSetConfigFailed−17SPI set config failed
I2cNack−18I²C target did not acknowledge
I2cBusError−19I²C bus error
I2cArbitrationLoss−20I²C arbitration loss
I2cOverrun−21I²C data overrun
BufferTooLong−22Argument exceeds its directional payload ceiling
I2cAddressOutOfRange−23I²C address out of valid range
GpioInvalidPin−24Invalid GPIO pin number
CommsFailed−25USB communication failure
I2cScanFailed−26I²C bus scan failed
GpioSetConfigFailed−27GPIO set config failed
GpioWrongDirection−28GPIO pin direction mismatch
I2cGetConfigFailed−29I²C get config failed
SpiGetConfigFailed−30SPI get config failed
UartReadFailed−31UART read failed
UartWriteFailed−32UART write failed
UartFlushFailed−33UART flush failed
UartOverrun−34UART receiver overrun
UartBreak−35UART break condition
UartParity−36UART parity error
UartFraming−37UART framing error
UartInvalidBaudRate−38Invalid baud rate
UartSetConfigFailed−39UART set config failed
UartGetConfigFailed−40UART get config failed
PwmSetDutyCycleFailed−41PWM set duty cycle failed
PwmGetDutyCycleFailed−42PWM get duty cycle failed
PwmEnableFailed−43PWM enable failed
PwmDisableFailed−44PWM disable failed
PwmSetConfigFailed−45PWM set config failed
PwmGetConfigFailed−46PWM get config failed
PwmInvalidChannel−47Invalid PWM channel
PwmInvalidDutyCycle−48Invalid PWM duty cycle
PwmInvalidConfiguration−49Invalid PWM configuration
AdcReadFailed−50ADC read failed
AdcGetConfigFailed−51ADC get config failed
AdcConversionFailed−52ADC conversion error
GpioPinMonitored−53Pin is currently subscribed
GpioPinNotMonitored−54Pin is not subscribed
GpioSubscribeFailed−55GPIO subscribe failed
GpioUnsubscribeFailed−56GPIO unsubscribe failed
OneWireNoPresence−571-Wire: no device responded to reset
OneWireBusError−581-Wire: bus communication error
OneWireReadFailed−591-Wire: read failed
OneWireWriteFailed−601-Wire: write failed
OneWireSearchFailed−611-Wire: ROM search failed
DeviceInfoFailed−62Device info query failed
SchemaMismatch−63Schema version mismatch between host and firmware
LegacyFirmware−64Firmware too old to support device/info
Unsupported−65Peripheral not available on this hardware revision
I2cBatchFailed−66I2C batch transaction failed
SpiBatchFailed−67SPI batch transaction failed
SpiTransferFailed−68SPI full-duplex transfer failed
SystemResetSubscriptionsFailed−69system/reset-subscriptions call failed
GpioTimeout−70GPIO wait timed out
SpiInvalidCsPin−71SPI chip-select index is outside the reported GPIO range
SpiCsPinUnavailable−72SPI chip-select pin is configured as an input
SpiCsPinMonitored−73SPI chip-select pin is monitored for GPIO events
SpiNoGpios−74Device reports zero GPIOs, so no chip-select pin exists
DeviceInfoTimeout−75device/info did not respond within 300 seconds
CallTimeout−76Device did not answer an RPC within its bound

CallTimeout (−76) means the request was transmitted but no reply arrived. It is deliberately distinct from CommsFailed (−25): the transport is healthy and the device very likely is too, so it is not a link failure. It is also distinct from DeviceInfoTimeout (−75), which covers only the validated metadata fetch and has a far longer bound. The handle stays usable, so the call may simply be retried — except after a batch, whose fate is unknown (it may have executed fully, partially, or not at all), so a blind retry there can repeat side effects.

BufferTooLong (−22) is also a host-side refusal. Data returned by the device is limited to GALLO_MAX_RESPONSE_PAYLOAD (1014 bytes), while data sent to it is limited to GALLO_MAX_TRANSFER_SIZE (4096 bytes). Full-duplex SPI transfer uses the tighter response ceiling. A batch is bounded a third way, by GALLO_MAX_REQUEST_FRAME (5119 bytes) on its whole request frame — the only bound on its aggregate outgoing bytes. The same status still represents a device-side buffer refusal, but an over-ceiling argument is rejected locally before transmission. Issues #158, #179 and #186 added no new Status value.

SpiInvalidCsPin (−71) and SpiNoGpios (−74) are host-side refusals: the chip-select was rejected before anything was transmitted, and no pin was driven. DeviceInfoFailed (−62), SchemaMismatch (−63), LegacyFirmware (−64) and DeviceInfoTimeout (−75) mean the host could not establish the device-reported GPIO count at all. Those four are never reported as a chip-select error: a failure to learn the valid range is not a complaint about the caller’s pin.

Source of Truth

The enum lives in crates/pico-de-gallo-ffi/src/lib.rs and is mirrored into the generated pico_de_gallo.h by cbindgen. If a code is missing from this table after a release, file an issue — that’s a documentation bug.