Driver API¶

These functions manage driver instances and operations that do not map directly to a single numbered datasheet command.

Instance acquisition, HAL configuration, result descriptions, and getters operate on software state without communicating with the radio. rfm12_apply_to_radio() and rfm12_software_reset() perform immediate SPI transfers through the configured HAL callback.

Data Types¶

RFM12_t¶

typedef struct RFM12 RFM12_t¶: Opaque driver instance. Obtain a pointer with rfm12_get_instance(); applications cannot access its fields or allocate it by value. Storage belongs to the driver and remains valid for the program lifetime. Do not free it.

RFM12_spi_transfer16_fn¶

typedef RFM12_result_t (*RFM12_spi_transfer16_fn)(void *context, uint16_t tx_word, uint16_t *rx_word)¶: Synchronous SPI transfer callback installed with rfm12_configure_hal(). The context pointer is passed through unchanged and may be NULL. Transmit the 16-bit tx_word and store the simultaneously received word through rx_word before returning. The platform callback manages chip select for the complete transfer. Return RFM12_OK on success or an RFM12_result_t error on failure; the driver propagates transfer errors. Keep the callback and any context storage valid while the instance uses them.

RFM12_result_t¶

type RFM12_result_t¶

Enum. Result returned by driver operations and the HAL callback. Zero indicates success. Use rfm12_result_string() for a readable description.

Constant	Value	Meaning
`RFM12_OK`	`0`	Operation succeeded.
`RFM12_ERROR_INVALID_HANDLE`	`1`	The device handle is NULL.
`RFM12_ERROR_INVALID_ARGUMENT`	`2`	An argument is NULL, out of range, or unsupported.
`RFM12_ERROR_INVALID_CONFIGURATION`	`3`	Staged settings are inconsistent or prerequisites are not satisfied.
`RFM12_ERROR_NO_INSTANCE_AVAILABLE`	`4`	The static instance pool is exhausted.
`RFM12_ERROR_NOT_INITIALIZED`	`5`	The SPI HAL callback has not been configured.
`RFM12_ERROR_UNKNOWN`	`6`	Unspecified error.

RFM12_enable_t¶

typedef bool RFM12_enable_t¶: Boolean enable/disable argument shared by command setters. RFM12_ENABLE is true and RFM12_DISABLE is false. Interpret the argument according to the named setting; for example, enabling the PLL dithering-disable setting disables dithering.

RFM12_ENABLE¶: Enable value: ((RFM12_enable_t)true).

RFM12_DISABLE¶: Disable value: ((RFM12_enable_t)false).

RFM12_mode_t¶

type RFM12_mode_t¶

Enum. Operating mode tracked in software and returned by rfm12_get_mode(). This is not a hardware status reading. Mode-entry helpers set it after a successful transfer; acquisition, reset, and manual changes to mode-defining power bits can leave it unknown.

Constant	Value	Meaning
`RFM12_MODE_UNKNOWN`	`0`	Mode is unknown.
`RFM12_MODE_STANDBY`	`1`	Crystal oscillator on; synthesizer, RX, TX, and baseband off.
`RFM12_MODE_IDLE`	`2`	Crystal oscillator and synthesizer on; RX, TX, and baseband off.
`RFM12_MODE_RX`	`3`	Receiver, baseband, synthesizer, and crystal oscillator on; TX off.
`RFM12_MODE_TX`	`4`	Transmitter, synthesizer, and crystal oscillator on; RX and baseband off.
`RFM12_MODE_SLEEP`	`5`	Receiver, transmitter, baseband, synthesizer, and crystal oscillator off.

Instance Management¶

Acquire statically allocated radio instances for use throughout the application.

rfm12_get_instance()¶

RFM12_result_t rfm12_get_instance(RFM12_t **instance)¶

Acquire the next available statically allocated radio instance and load its staged defaults. No SPI transaction is performed.

The instance remains valid for the lifetime of the program and must not be freed. Instances cannot be released or reused. This function is intended for application initialization and is not thread-safe.

Parameters:

instance – Receives the opaque radio handle; set to NULL when acquisition fails.

Returns:

RFM12_OK on success, RFM12_ERROR_NO_INSTANCE_AVAILABLE when the instance pool is exhausted, or an appropriate RFM12_result_t error.

Hardware Abstraction¶

Connect a radio instance to the platform SPI implementation through its HAL callback and context.

rfm12_configure_hal()¶

RFM12_result_t rfm12_configure_hal(RFM12_t *dev, RFM12_spi_transfer16_fn function, void *context)¶

Associate a radio instance with its synchronous 16-bit SPI callback and platform context. No SPI transaction is performed.

The context is passed unchanged to every callback invocation. The callback transmits the supplied word, stores the simultaneously received word through its output pointer, and returns an RFM12_result_t.

Parameters:

dev – RFM12 radio instance.
function – SPI transfer callback; must not be NULL.
context – Opaque platform context passed to the callback; may be NULL.

Returns:

RFM12_OK on success, or an appropriate RFM12_result_t error.

Configuration¶

Validate staged settings and apply pending configuration to the radio.

rfm12_apply_to_radio()¶

RFM12_result_t rfm12_apply_to_radio(RFM12_t *dev)¶

Validate dependent staged settings and transmit all pending configuration command groups to the radio.

Groups marked dirty contain pending settings. Clean groups are skipped, and the Power Management Command is sent last. Each command group is marked clean after its transfer succeeds.

If a transfer fails, the failed and remaining groups stay dirty for a later retry. Groups already transferred successfully remain clean.

Parameters:

dev – RFM12 radio instance containing staged configuration and pending-command flags, which are updated as transfers succeed.

Returns:

RFM12_OK on success, or an appropriate RFM12_result_t validation or transfer error.

Device Control¶

Perform immediate device operations, such as resetting the physical radio.

rfm12_software_reset()¶

RFM12_result_t rfm12_software_reset(RFM12_t *dev)¶

Immediately enable sensitive reset and send the special 0xFE00 software-reset command to the radio.

The HAL configuration and staged settings are preserved. Pending configuration is not applied before the reset. After a successful reset sequence, all configuration groups are marked dirty so they can be restored with rfm12_apply_to_radio().

Note

This function does not provide the required hardware startup delay. Wait for the radio to complete its reset/startup delay before applying the staged configuration again.

Parameters:

dev – RFM12 radio instance whose physical radio will be reset.

Returns:

RFM12_OK on success, or an appropriate RFM12_result_t error.

Driver State¶

Inspect the tracked operating mode and synchronization settings stored by the driver without reading the physical radio.

rfm12_get_mode()¶

RFM12_result_t rfm12_get_mode(const RFM12_t *dev, RFM12_mode_t *mode)¶

Get the driver’s tracked operating mode.

This is software state; the function does not read the physical radio. The tracked value may be RFM12_MODE_UNKNOWN, particularly after instance acquisition, software reset, or manual changes to mode-defining power bits.

Parameters:

dev – RFM12 radio instance.
mode – Receives the tracked operating mode.

Returns:

RFM12_OK on success, or an appropriate RFM12_result_t error.

rfm12_get_sync_bytes()¶

RFM12_result_t rfm12_get_sync_bytes(const RFM12_t *dev, uint8_t *buffer, uint8_t buffer_size, uint8_t *length)¶

Build the synchronization sequence represented by the staged FIFO and Sync Pattern settings. No SPI transaction is performed.

One-byte mode returns the programmable synchronization byte. Two-byte mode returns the fixed byte 0x2D followed by the programmable byte. The buffer must hold at least one byte or two bytes, respectively.

Parameters:

dev – RFM12 radio instance containing the staged synchronization settings.
buffer – Receives the synchronization bytes.
buffer_size – Available buffer size in bytes.
length – Receives the number of synchronization bytes written.

Returns:

RFM12_OK on success, or an appropriate RFM12_result_t error.

Error Handling¶

Translate driver result codes into readable descriptions for diagnostics.

rfm12_result_string()¶

const char *rfm12_result_string(RFM12_result_t result)¶

Return a static, human-readable description of a driver result code.

No SPI transaction is performed. The returned string must not be modified or freed. Unknown numeric values produce an Unrecognized result code description.

Parameters:

result – Result code to describe.

Returns:

Pointer to a static string describing the result code.