sdr_observer.h File Reference

Experimental SDR observation operator with RTL-SDR and synthetic fallback status. More...

#include "oakfield/operator_split.h"
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for sdr_observer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimSdrObserverConfig
	Configuration for an SDR observer operator. More...
struct	SimSdrObserverStatus
	Runtime status snapshot for an SDR observer operator. More...

Macros
#define	SIM_SDR_OBSERVER_STATUS_MESSAGE_MAX   159U

Typedefs
typedef enum SimSdrObserverDemod	SimSdrObserverDemod
	Demodulation mode applied to observed SDR IQ samples.
typedef enum SimSdrObserverBackendMode	SimSdrObserverBackendMode
	Active SDR sample backend.
typedef enum SimSdrObserverFallbackReason	SimSdrObserverFallbackReason
	Reason the observer most recently fell back from hardware input.
typedef struct SimSdrObserverConfig	SimSdrObserverConfig
	Configuration for an SDR observer operator.
typedef struct SimSdrObserverStatus	SimSdrObserverStatus
	Runtime status snapshot for an SDR observer operator.

Enumerations
enum	SimSdrObserverDemod { SIM_SDR_OBSERVER_DEMOD_RAW = 0 , SIM_SDR_OBSERVER_DEMOD_AM , SIM_SDR_OBSERVER_DEMOD_FM , SIM_SDR_OBSERVER_DEMOD_PM }
	Demodulation mode applied to observed SDR IQ samples. More...
enum	SimSdrObserverBackendMode { SIM_SDR_OBSERVER_BACKEND_UNKNOWN = 0 , SIM_SDR_OBSERVER_BACKEND_SYNTHETIC , SIM_SDR_OBSERVER_BACKEND_RTL_SDR }
	Active SDR sample backend. More...
enum	SimSdrObserverFallbackReason {   SIM_SDR_OBSERVER_FALLBACK_NONE = 0 , SIM_SDR_OBSERVER_FALLBACK_RTLSDR_DISABLED , SIM_SDR_OBSERVER_FALLBACK_DEVICE_OPEN_FAILED , SIM_SDR_OBSERVER_FALLBACK_DEVICE_CONFIG_FAILED ,   SIM_SDR_OBSERVER_FALLBACK_BUFFER_ALLOCATION_FAILED , SIM_SDR_OBSERVER_FALLBACK_READ_FAILED }
	Reason the observer most recently fell back from hardware input. More...

Functions
const char *	sim_sdr_observer_backend_mode_name (SimSdrObserverBackendMode mode)
	Return the schema name for an SDR backend mode.
const char *	sim_sdr_observer_fallback_reason_name (SimSdrObserverFallbackReason reason)
	Return the schema name for an SDR fallback reason.
SimResult	sim_add_sdr_observer_operator (struct SimContext *context, const SimSdrObserverConfig *config, size_t *out_index)
	Register an experimental SDR observer operator.
SimResult	sim_sdr_observer_config (struct SimContext *context, size_t operator_index, SimSdrObserverConfig *out_config)
	Copy the current SDR observer configuration from a registered operator.
SimResult	sim_sdr_observer_status (struct SimContext *context, size_t operator_index, SimSdrObserverStatus *out_status)
	Copy runtime status from a registered experimental SDR observer.
SimResult	sim_sdr_observer_update (struct SimContext *context, size_t operator_index, const SimSdrObserverConfig *config)
	Replace the configuration of a registered experimental SDR observer.

Detailed Description

Experimental SDR observation operator with RTL-SDR and synthetic fallback status.

Warning

Experimental API. Backend ownership, blocking/timing behavior, demodulation placement, status fields, and fallback semantics may change while the SDR stack moves toward production-grade capture.

Enumeration Type Documentation

SimSdrObserverBackendMode

enum SimSdrObserverBackendMode

Active SDR sample backend.

Enumerator
SIM_SDR_OBSERVER_BACKEND_UNKNOWN	Backend has not been selected.
SIM_SDR_OBSERVER_BACKEND_SYNTHETIC	Deterministic synthetic fallback source.
SIM_SDR_OBSERVER_BACKEND_RTL_SDR	RTL-SDR hardware source.

SimSdrObserverDemod

enum SimSdrObserverDemod

Demodulation mode applied to observed SDR IQ samples.

Enumerator
SIM_SDR_OBSERVER_DEMOD_RAW	Raw IQ passthrough into complex field.
SIM_SDR_OBSERVER_DEMOD_AM	Amplitude envelope demodulation.
SIM_SDR_OBSERVER_DEMOD_FM	Instantaneous frequency deviation.
SIM_SDR_OBSERVER_DEMOD_PM	Instantaneous phase.

SimSdrObserverFallbackReason

enum SimSdrObserverFallbackReason

Reason the observer most recently fell back from hardware input.

Enumerator
SIM_SDR_OBSERVER_FALLBACK_NONE	Hardware fallback has not occurred.
SIM_SDR_OBSERVER_FALLBACK_RTLSDR_DISABLED	Build or runtime configuration disabled RTL-SDR.
SIM_SDR_OBSERVER_FALLBACK_DEVICE_OPEN_FAILED	Device open failed.
SIM_SDR_OBSERVER_FALLBACK_DEVICE_CONFIG_FAILED	Device configuration failed.
SIM_SDR_OBSERVER_FALLBACK_BUFFER_ALLOCATION_FAILED	IQ read buffer allocation failed.
SIM_SDR_OBSERVER_FALLBACK_READ_FAILED	Hardware read failed.

Function Documentation

sim_add_sdr_observer_operator()

SimResult sim_add_sdr_observer_operator	(	struct SimContext *	context,
		const SimSdrObserverConfig *	config,
		size_t *	out_index
	)

Register an experimental SDR observer operator.

Parameters

	context	Simulation context that will own the operator.
	config	Optional SDR observer configuration; NULL selects normalized defaults.
[out]	out_index	Optional destination for the registered operator index.

Returns

SIM_RESULT_OK on success, or an error code from argument validation, field validation, allocation, backend setup, or split registration.

sim_sdr_observer_backend_mode_name()

const char * sim_sdr_observer_backend_mode_name

(

SimSdrObserverBackendMode

mode

)

Return the schema name for an SDR backend mode.

Parameters

mode	Backend mode enum value.

Returns

Stable lowercase backend mode name.

sim_sdr_observer_config()

SimResult sim_sdr_observer_config	(	struct SimContext *	context,
		size_t	operator_index,
		SimSdrObserverConfig *	out_config
	)

Copy the current SDR observer configuration from a registered operator.

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_sdr_observer_operator().
[out]	out_config	Receives the normalized configuration.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no observer state.

sim_sdr_observer_fallback_reason_name()

const char * sim_sdr_observer_fallback_reason_name

(

SimSdrObserverFallbackReason

reason

)

Return the schema name for an SDR fallback reason.

Parameters

reason

Fallback reason enum value.

Returns

Stable lowercase reason name.

sim_sdr_observer_status()

SimResult sim_sdr_observer_status	(	struct SimContext *	context,
		size_t	operator_index,
		SimSdrObserverStatus *	out_status
	)

Copy runtime status from a registered experimental SDR observer.

Status includes active backend, fallback reason, read counters, and sticky backend error details.

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_sdr_observer_operator().
[out]	out_status	Receives the current observer status snapshot.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no observer state.

sim_sdr_observer_update()

SimResult sim_sdr_observer_update	(	struct SimContext *	context,
		size_t	operator_index,
		const SimSdrObserverConfig *	config
	)

Replace the configuration of a registered experimental SDR observer.

config is required. A successful update refreshes backend state and invalidates the scheduler plan.

Parameters

context	Simulation context containing the operator.
operator_index	Index of the SDR observer to update.
config	Replacement SDR observer configuration.

Returns

SIM_RESULT_OK on success, or an error code from argument validation, lookup, field validation, backend setup, or state validation.