Collaboration diagram for Human Interface Device (HID):

Modules
	Events
	HID event types/payloads, the keycode/state definitions they carry (see keycode.h), and the hid_event_queue_*()/hid_event_free() functions that produce and release them.

	Keycodes
	Numeric HID keycode constants.

Files
file	device.h
	HID device lifecycle and polling interface.

Data Structures
struct	hid_device_callbacks_t
	Callback operation table for HID device backends. More...

Macros
#define	HID_DEVICE_CAPACITY 32u
	Maximum number of HID devices tracked by one HID instance. More...

#define	HID_DEVICE_CONTEXT_SIZE 32u
	Size in bytes of the per-device scratch context space embedded in every hid_device_t. More...

Typedefs
typedef struct hid_t	hid_t
	Opaque HID instance handle.

typedef struct hid_device_t	hid_device_t
	HID child-device descriptor tracked by a HID instance.

Enumerations
enum	hid_type_t { hid_type_none = 0, hid_type_gpio = 1, hid_type_timer = 2, hid_type_signal = 3, hid_type_evdev = 4, hid_type_usb = 5, hid_type_wifi = 6, hid_type_bluetooth = 7, hid_type_infrared = 8, hid_type_other = 9, hid_type_iostream = 10 }
	HID device type classification.

enum	hid_class_t { hid_class_unknown = 0, hid_class_keyboard = 1, hid_class_mouse = 2, hid_class_joystick = 3, hid_class_touchscreen = 4, hid_class_sensor = 5 }
	Coarse semantic classification of a HID device. More...

Lifecycle
hid_t *	hid_init (sys_event_queue_t *queue)
	Initialize a HID device instance. More...

void	hid_deinit (hid_t *instance)
	Deinitialize a HID device instance. More...

bool	hid_poll (hid_t *instance)
	Poll a HID device for pending input. More...

Methods
hid_device_t *	hid_register (hid_t instance, const char name, uint32_t id, hid_type_t type, hid_class_t hid_class, uint32_t polling_interval_ms, void *userdata, hid_device_callbacks_t callbacks)
	Register a generic HID device using callback operations. More...

hid_device_t *	hid_register_gpio_input (hid_t instance, uint8_t bank, uint8_t pin, uint16_t keycode, void userdata)
	Register a GPIO pin as HID input. More...

hid_device_t *	hid_register_gpio_pullup (hid_t instance, uint8_t bank, uint8_t pin, uint16_t keycode, void userdata)
	Register a GPIO pin as HID input with pull-up. More...

hid_device_t *	hid_register_gpio_pulldown (hid_t instance, uint8_t bank, uint8_t pin, uint16_t keycode, void userdata)
	Register a GPIO pin as HID input with pull-down. More...

hid_device_t *	hid_register_adc (hid_t instance, uint8_t channel, const char metric_name, uint16_t num_samples, uint32_t polling_interval_ms, void *userdata)
	Register an ADC channel as a polling HID metric source. More...

hid_device_t *	hid_register_temperature (hid_t instance, uint32_t polling_interval_ms, void userdata)
	Register the internal temperature-sensor channel as a polling HID metric source. More...

hid_device_t *	hid_register_user_button (hid_t instance, uint16_t keycode, void userdata)
	Register a user button as a HID input source. More...

hid_device_t *	hid_register_timer (hid_t instance, uint32_t id, uint32_t interval_ms, bool repeating, void userdata)
	Register a timer-backed HID source. More...

hid_device_t *	hid_register_signal (hid_t instance, void userdata)
	Register an environment-signal HID source. More...

hid_device_t *	hid_register_wifi (hid_t instance, hw_wifi_t wifi, void *userdata)
	Register a Wi-Fi connection-state observer. More...

hid_device_t *	hid_register_iostream (hid_t instance, sys_iostream_t stream, void *userdata)
	Register a stream-readiness observer. More...

bool	hid_deregister (hid_t instance, hid_device_t device)
	Deregister and remove a HID device. More...

Properties
hid_device_t *	hid_device_next (hid_device_t *device)
	Enumerate registered HID devices. More...

bool	hid_device_info (const hid_device_t device, const char out_name, uint32_t out_id, hid_type_t out_type, hid_class_t out_class)
	Get metadata for a registered HID device. More...

void *	hid_device_userdata (const hid_device_t *device)
	Get the userdata pointer associated with a registered HID device. More...

void *	hid_device_handle (const hid_device_t *device)
	Get a device's backend-owned handle, if it has one. More...

Detailed Description

The HID module provides a unified event-oriented interface for input and sensor-like producers, including GPIO-backed keys, timer sources, touch controllers, signal notifications, and device-specific integrations.

A HID instance is created with hid_init() and bound to a system event queue. Backends register one or more HID devices under that instance, either through generic registration (hid_register) or convenience helpers such as timer and GPIO registration functions.

During runtime, applications call hid_poll() to let registered backends produce events. Produced events are queued as hid_event_t values and consumed by the application event loop. The event payload union carries the event-specific data for keycodes, timers, touch coordinates, metrics, and signals.

Typical flow:

Create a queue and initialize HID with hid_init().
Register one or more HID devices/sources.
Call hid_poll() regularly (or from a runloop poll callback).
Handle queued hid_event_t events and release each with hid_event_free().
On shutdown, hid_deinit() will clean up devices and resources.

Macro Definition Documentation

◆ HID_DEVICE_CAPACITY

#define HID_DEVICE_CAPACITY 32u

Maximum number of HID devices tracked by one HID instance.

Override at compile time, for example: -DHID_DEVICE_CAPACITY=16.

Definition at line 19 of file device.h.

◆ HID_DEVICE_CONTEXT_SIZE

#define HID_DEVICE_CONTEXT_SIZE 32u

Size in bytes of the per-device scratch context space embedded in every hid_device_t.

Override at compile time, for example: -DHID_DEVICE_CONTEXT_SIZE=64.

Definition at line 30 of file device.h.

Enumeration Type Documentation

◆ hid_class_t

enum hid_class_t

Coarse semantic classification of a HID device.

Unlike hid_type_t (which identifies the backend mechanism, e.g. gpio vs evdev vs timer), this describes what kind of thing the device is to an application. For evdev devices this is determined heuristically from the event/key/axis capability bits the kernel reports for the device node; see hid_evdev_list().

Definition at line 93 of file device.h.

              {
   hid_class_unknown = 0,
   hid_class_keyboard = 1,
   hid_class_mouse = 2,
   hid_class_joystick = 3,
   hid_class_touchscreen = 4,
   hid_class_sensor = 5,
 } hid_class_t;

Function Documentation

◆ hid_deinit()

void hid_deinit ( hid_t * instance )

Deinitialize a HID device instance.

Parameters

instance HID instance.

◆ hid_deregister()

bool hid_deregister	(	hid_t *	instance,
		hid_device_t *	device
	)

Deregister and remove a HID device.

Parameters

instance	HID instance that owns the device.
device	HID device handle.

Return values

true	Device was removed.
false	Instance or device handle was invalid.

◆ hid_device_handle()

void* hid_device_handle ( const hid_device_t * device )

Get a device's backend-owned handle, if it has one.

Parameters

device HID device handle.

Returns: The device's own backend handle - a hw_gpio_t* for hid_type_gpio (including hid_register_user_button()), a hw_wifi_t* for hid_type_wifi, a sys_timer_t* for hid_type_timer, a sys_iostream_t* for hid_type_iostream, or a hw_adc_t* for an ADC/temperature device (hid_type_other, hid_class_sensor) - or NULL if the handle is invalid or this device type has no single such handle (e.g. hid_type_signal, or a generic hid_register() device).

Distinct from hid_device_userdata(), which always returns the caller's own opaque pointer instead - see its own doc. Intended for driving the backend directly (e.g. hw_gpio_set_mode(), hw_wifi_scan()) alongside the events HID already produces for it.

◆ hid_device_info()

bool hid_device_info	(	const hid_device_t *	device,
		const char **	out_name,
		uint32_t *	out_id,
		hid_type_t *	out_type,
		hid_class_t *	out_class
	)

Get metadata for a registered HID device.

Parameters

device	HID device handle.
out_name	Receives device name when non-NULL.
out_id	Receives device id when non-NULL.
out_type	Receives device type when non-NULL.
out_class	Receives device classification when non-NULL. Devices registered with hid_class_unknown (the default choice when no more specific classification applies) report hid_class_unknown here.

Return values

true	Metadata was returned.
false	Device handle was invalid.

◆ hid_device_next()

hid_device_t* hid_device_next ( hid_device_t * device )

Enumerate registered HID devices.

Parameters

device Current device pointer, or NULL to get the first device.

Returns: Next device pointer, or NULL when no more devices are available.

◆ hid_device_userdata()

void* hid_device_userdata ( const hid_device_t * device )

Get the userdata pointer associated with a registered HID device.

Parameters

device HID device handle.

Returns: Whatever userdata the device was registered with (see hid_register() and the various hid_register_*() convenience functions), or NULL when the handle is invalid or no userdata was supplied.

This is always the caller's own opaque pointer, uniformly across every registration function - it never aliases a backend's own hardware/system handle (see hid_device_handle() for that).

◆ hid_init()

hid_t* hid_init ( sys_event_queue_t * queue )

Initialize a HID device instance.

Parameters

queue Event queue used by this HID instance.

Returns: HID instance, or NULL on failure.

◆ hid_poll()

bool hid_poll ( hid_t * instance )

Poll a HID device for pending input.

Parameters

instance HID instance.

Return values

true	Input was processed.
false	No input was available or the device is invalid.

◆ hid_register()

hid_device_t* hid_register	(	hid_t *	instance,
		const char *	name,
		uint32_t	id,
		hid_type_t	type,
		hid_class_t	hid_class,
		uint32_t	polling_interval_ms,
		void *	userdata,
		hid_device_callbacks_t	callbacks
	)

Register a generic HID device using callback operations.

Parameters

instance	HID instance that owns the registration.
name	Device name.
id	Device identifier.
type	Device type (backend mechanism) classification.
hid_class	Device semantic classification (see hid_class_t). Pass hid_class_unknown when none applies.
polling_interval_ms	Polling interval in milliseconds for read callbacks. Use 0 to evaluate on every hid_poll() call.
userdata	Opaque user data passed to callback functions.
callbacks	Callback operation table.

Returns: Registered HID device descriptor, or NULL on failure.

◆ hid_register_adc()

hid_device_t* hid_register_adc	(	hid_t *	instance,
		uint8_t	channel,
		const char *	metric_name,
		uint16_t	num_samples,
		uint32_t	polling_interval_ms,
		void *	userdata
	)

Register an ADC channel as a polling HID metric source.

Parameters

instance	HID instance that owns the registration.
channel	ADC channel number (see `hw_adc_gpio_pin()`/ `hw_adc_gpio_channel()`). Must be backed by a GPIO pin on the current platform; use hid_register_temperature for the internal temperature-sensor channel instead.
metric_name	Name reported on the published metric event. Must remain valid for the lifetime of the registration (a string literal is fine); NULL defaults to `"raw_16"`.
num_samples	Number of ADC conversions to average per read (see `hw_adc_read_16()`). 0 or 1 takes a single, immediate reading.
polling_interval_ms	Polling interval in milliseconds.

Passing 0 uses a default interval of 5000 ms.

Parameters

userdata Opaque user data retrievable via hid_device_userdata() on the returned device. To reach the backing hw_adc_t* handle instead, use hid_device_handle().

Returns: Registered HID device descriptor, or NULL on failure (for example, if the channel has no GPIO pin).

Resolves the channel to its GPIO pin (hw_adc_gpio_pin()), reads it on every poll, and publishes a hid_event_type_metric event named metric_name (0-65535) whenever the value has changed since the last poll, the same change-detection behavior hid_register_temperature itself uses for the internal temperature-sensor channel. No temperature metric is reported here; see hid_register_temperature for that.

◆ hid_register_gpio_input()

hid_device_t* hid_register_gpio_input	(	hid_t *	instance,
		uint8_t	bank,
		uint8_t	pin,
		uint16_t	keycode,
		void *	userdata
	)

Register a GPIO pin as HID input.

Parameters

instance	HID instance that owns the GPIO registration.
bank	GPIO bank index.
pin	GPIO pin index.
keycode	HID keycode reported for this input.
userdata	Opaque user data retrievable via hid_device_userdata() on the returned device. To reach the backing hw_gpio_t* handle instead (e.g. to call hw_gpio_set_mode() directly), use hid_device_handle().

Returns: Registered HID device descriptor, or NULL on failure.

◆ hid_register_gpio_pulldown()

hid_device_t* hid_register_gpio_pulldown	(	hid_t *	instance,
		uint8_t	bank,
		uint8_t	pin,
		uint16_t	keycode,
		void *	userdata
	)

Register a GPIO pin as HID input with pull-down.

Parameters

instance	HID instance that owns the GPIO registration.
bank	GPIO bank index.
pin	GPIO pin index.
keycode	HID keycode reported for this input.
userdata	Opaque user data retrievable via hid_device_userdata() - see hid_register_gpio_input()'s own doc.

Returns: Registered HID device descriptor, or NULL on failure.

◆ hid_register_gpio_pullup()

hid_device_t* hid_register_gpio_pullup	(	hid_t *	instance,
		uint8_t	bank,
		uint8_t	pin,
		uint16_t	keycode,
		void *	userdata
	)

Register a GPIO pin as HID input with pull-up.

Parameters

instance	HID instance that owns the GPIO registration.
bank	GPIO bank index.
pin	GPIO pin index.
keycode	HID keycode reported for this input.
userdata	Opaque user data retrievable via hid_device_userdata() - see hid_register_gpio_input()'s own doc.

Returns: Registered HID device descriptor, or NULL on failure.

◆ hid_register_iostream()

hid_device_t* hid_register_iostream	(	hid_t *	instance,
		sys_iostream_t *	stream,
		void *	userdata
	)

Register a stream-readiness observer.

Parameters

instance	HID instance that owns the registration.
stream	Already-open stream, from sys_string_read()/_open(), sys_stdin/sys_stdout, or a hardware-backed stream such as hw_uart_init()'s. HID does not create, own, or close this stream - only observes it - so whichever part of the program opened it is responsible for eventually calling sys_iostream_close() on it.
userdata	Opaque user data retrievable via hid_device_userdata() on the returned device. To reach `stream` itself instead, use hid_device_handle().

Returns: Registered HID device descriptor, or NULL on failure (for example, if stream is NULL or its backend doesn't support readiness notifications - see sys_iostream_set_callback()).

Attaches a callback to stream via sys_iostream_set_callback() and emits a hid_event_type_iostream event whenever it becomes ready for reading and/or writing (see sys_iostream_event_t) - most usefully, when there is data available to read without blocking. Like hid_register_wifi(), sys_iostream_set_callback() replaces whatever callback stream already had attached, if any.

This registers an observer only; it does not read or write stream itself. Retrieve it via hid_device_handle() on the returned device and call sys_iostream_read()/_write()/_peek() directly.

hid_deregister() detaches the callback (equivalent to sys_iostream_set_callback(stream, NULL, NULL)) but leaves stream itself open.

◆ hid_register_signal()

hid_device_t* hid_register_signal	(	hid_t *	instance,
		void *	userdata
	)

Register an environment-signal HID source.

Parameters

instance	HID instance that owns the signal registration.
userdata	Opaque user data retrievable via hid_device_userdata() on the returned device.

Returns: Registered HID device descriptor, or NULL on failure.

The signal source captures environment signals and emits hid_event_type_signal events when those signals are observed.

◆ hid_register_temperature()

hid_device_t* hid_register_temperature	(	hid_t *	instance,
		uint32_t	polling_interval_ms,
		void *	userdata
	)

Register the internal temperature-sensor channel as a polling HID metric source.

Parameters

instance	HID instance that owns the registration.
polling_interval_ms	Polling interval in milliseconds.

Passing 0 uses a default interval of 5000 ms.

Parameters

userdata Opaque user data retrievable via hid_device_userdata() - see hid_register_adc()'s own doc.

Returns: Registered HID device descriptor, or NULL on failure (for example, if the platform has no internal temperature sensor).

Reads the internal temperature-sensor ADC channel (see hw_adc_init_temperature()), averaged over a fixed number of samples internal to this module, on every poll and publishes a hid_event_type_metric "temp" (degrees Celsius) event whenever the value has changed since the last poll. See hid_register_adc for a GPIO-pin ADC source with a caller-controlled sample count.

◆ hid_register_timer()

hid_device_t* hid_register_timer	(	hid_t *	instance,
		uint32_t	id,
		uint32_t	interval_ms,
		bool	repeating,
		void *	userdata
	)

Register a timer-backed HID source.

Parameters

instance	HID instance that owns the timer registration.
id	Device identifier.
interval_ms	Timer period in milliseconds.
repeating	True for periodic timers, false for one-shot timers.
userdata	Opaque user data retrievable via hid_device_userdata() and forwarded as hid_timer_t.userdata on every event this timer fires. To reach the backing sys_timer_t* handle instead, use hid_device_handle().

Returns: Registered HID device descriptor, or NULL on failure.

For repeating == false, do not call hid_deregister() once the timer fires - the device is automatically deregistered when its hid_event_type_timer event is released with hid_event_free(); see that function's own doc.

◆ hid_register_user_button()

hid_device_t* hid_register_user_button	(	hid_t *	instance,
		uint16_t	keycode,
		void *	userdata
	)

Register a user button as a HID input source.

Parameters

instance	HID instance that owns the user-button registration.
keycode	HID keycode reported for this input.
userdata	Opaque user data retrievable via hid_device_userdata() - see hid_register_gpio_input()'s own doc.

Returns: Registered HID device descriptor, or NULL on failure.

◆ hid_register_wifi()

hid_device_t* hid_register_wifi	(	hid_t *	instance,
		hw_wifi_t *	wifi,
		void *	userdata
	)

Register a Wi-Fi connection-state observer.

Parameters

instance	HID instance that owns the Wi-Fi registration.
wifi	Already-initialized Wi-Fi handle, from hw_wifi_init_client(), hw_wifi_init_accesspoint(), or hw_wifi_init_device(). HID does not create, own, or deinitialize this handle - only observes it - so whichever part of the program brought the radio up is responsible for eventually calling hw_wifi_deinit() on it.
userdata	Opaque user data retrievable via hid_device_userdata() on the returned device. To reach `wifi` itself instead, use hid_device_handle().

Returns: Registered HID device descriptor, or NULL on failure (for example, if wifi is NULL).

Attaches a callback to wifi via hw_wifi_set_callback() and emits a hid_event_type_wifi event for every status change it reports (joining, connected, disconnected, scan results, errors — see hw_wifi_event_t). hw_wifi_set_callback() replaces whatever callback wifi already had attached, if any - this and any other code that also wants to observe wifi directly will conflict with each other over that single slot.

This registers an observer only; it does not expose scan/connect/ disconnect actions. To drive the connection, retrieve wifi via hid_device_handle() on the returned device and call hw_wifi_scan()/hw_wifi_connect()/hw_wifi_disconnect() directly (mirroring how hid_type_gpio devices expose their backing hw_gpio_t* the same way).

hid_deregister() detaches the callback (equivalent to hw_wifi_set_callback(wifi, NULL, NULL)) but leaves wifi itself initialized.

picofuse

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Lifecycle

Methods

Properties

Detailed Description

Macro Definition Documentation

◆ HID_DEVICE_CAPACITY

◆ HID_DEVICE_CONTEXT_SIZE

Enumeration Type Documentation

◆ hid_class_t

Function Documentation

◆ hid_deinit()

◆ hid_deregister()

◆ hid_device_handle()

◆ hid_device_info()

◆ hid_device_next()

◆ hid_device_userdata()

◆ hid_init()

◆ hid_poll()

◆ hid_register()

◆ hid_register_adc()

◆ hid_register_gpio_input()

◆ hid_register_gpio_pulldown()

◆ hid_register_gpio_pullup()

◆ hid_register_iostream()

◆ hid_register_signal()

◆ hid_register_temperature()

◆ hid_register_timer()

◆ hid_register_user_button()

◆ hid_register_wifi()