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. More...

Collaboration diagram for Events:

Files
file	keycode.h
	HID keycode and input-state definitions.

Data Structures
struct	hid_keycode_t
	Keycode-oriented HID event payload. More...
struct	hid_touch_t
	Touch-oriented HID event payload. More...
struct	hid_metric_t
	Metric-oriented HID event payload. More...
struct	hid_timer_t
	Timer-oriented HID event payload. More...
struct	hid_signal_t
	Signal-oriented HID event payload. More...
struct	hid_wifi_t
	Wi-Fi-oriented HID event payload. More...
struct	hid_usb_t
	USB-hotplug-oriented HID event payload. More...
struct	hid_iostream_t
	Stream-readiness-oriented HID event payload. More...
struct	hid_time_t
	Time-oriented HID event payload. More...
struct	hid_event_t
	Represents a single HID input event. More...

Macros
#define	HID_EVENT_CAPACITY   16u
	Maximum number of in-flight HID events tracked by one HID instance. More...

Enumerations
enum	hid_event_type_t {   hid_event_type_none = 0, hid_event_type_keycode = 1, hid_event_type_touch = 2, hid_event_type_metric = 3,   hid_event_type_timer = 4, hid_event_type_signal = 5, hid_event_type_wifi = 6, hid_event_type_iostream = 7,   hid_event_type_time = 8, hid_event_type_usb = 9 }
	HID event payload selector.
enum	hid_state_t {   hid_state_none = 0, hid_state_on = (1 << 0), hid_state_off = (1 << 1), hid_state_rising = hid_state_on,   hid_state_falling = hid_state_off, hid_state_click = (1 << 2), hid_state_double_click = (1 << 3), hid_state_triple_click = (1 << 4),   hid_state_long_click, hid_state_repeat = (1 << 6), hid_state_function = (1 << 7), hid_state_caps_lock = (1 << 8),   hid_state_num_lock = (1 << 9), hid_state_scroll_lock = (1 << 10), hid_state_left_shift = (1 << 11), hid_state_right_shift = (1 << 12),   hid_state_left_meta = (1 << 13), hid_state_right_meta, hid_state_left_alt = (1 << 15), hid_state_right_alt = (1 << 16),   hid_state_left_control = (1 << 17), hid_state_right_control = (1 << 18), hid_state_left_windows = (1 << 19), hid_state_right_windows,   hid_state_shift, hid_state_meta, hid_state_alt, hid_state_control,   hid_state_windows }
	Input state flags used by the input manager and key handling. More...

Functions
bool	hid_event_queue_keycode (hid_device_t *device, hid_state_t state, uint16_t keycode)
	Queue a keycode-based HID event to the owning HID instance queue. More...
bool	hid_event_queue_metric_float (hid_device_t *device, const char *name, const char *unit, float value)
	Queue a float metric HID event to a HID instance queue. More...
bool	hid_event_queue_touch (hid_device_t *device, hid_state_t state, pix_point_t point, uint8_t slot)
	Queue a touch HID event to the owning HID instance queue. More...
bool	hid_event_queue_signal (hid_device_t *device, sys_env_signal_t signal)
	Queue a signal HID event to the owning HID instance queue. More...
bool	hid_event_queue_wifi (hid_device_t *device, hw_wifi_event_t event, const hw_wifi_network_t *network)
	Queue a Wi-Fi status HID event to the owning HID instance queue. More...
bool	hid_event_queue_usb (hid_device_t *device, hw_usb_event_t event, const hw_usb_device_t *usb_device)
	Queue a USB hotplug HID event to the owning HID instance queue. More...
bool	hid_event_queue_iostream (hid_device_t *device, sys_iostream_event_t events)
	Queue a stream-readiness HID event to the owning HID instance queue. More...
bool	hid_event_queue_time (hid_device_t *device, const sys_date_t *date)
	Queue a time HID event to the owning HID instance queue. More...
void	hid_event_free (hid_event_t *event)
	Free a HID event allocated internally by HID queue helpers. More...
size_t	hid_state_to_string (hid_state_t state, char *buf, size_t buf_size)
	Format a HID state bitmask as a "|"-separated list of active flag names (for example "on|left_shift"). More...

Detailed Description

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.

Events are received from the sys_event_queue_t* that was passed to hid_init() when the HID instance was created - pop from it with sys_event_queue_pop()/_try_pop()/_timed_pop() and cast the returned sys_event_t back to a hid_event_t*. hid_poll() and the various backends (gpio/timer/signal/wifi/...) are what push events onto that queue in the first place, via the hid_event_queue_*() functions below.

Every popped event is owned by whichever consumer popped it, and comes from a fixed-size internal pool (see HID_EVENT_CAPACITY), not the heap

• so it must be released with hid_event_free() once handled, or that pool slot is leaked for the remaining lifetime of the HID instance. For a one-shot hid_register_timer() device specifically, freeing its event is also what finally deregisters the device - see hid_event_free()'s own doc.

Macro Definition Documentation

HID_EVENT_CAPACITY

#define HID_EVENT_CAPACITY   16u

Maximum number of in-flight HID events tracked by one HID instance.

An event occupies a pool slot from the point it's queued (by a hid_event_queue_*() helper) until the consumer releases it with hid_event_free(). Override at compile time, for example: -DHID_EVENT_CAPACITY=64.

Definition at line 47 of file event.h.

Enumeration Type Documentation

hid_state_t

enum hid_state_t

Input state flags used by the input manager and key handling.

This set of bitflags describes instantaneous and latent input states for buttons and keys. Flags are combined with bitwise-or to represent simultaneous conditions (for example, a key that is down and also generates a click event). Use bit tests to query states, e.g. if ((state & hid_state_shift) != 0) { ... }.

Enumerator
hid_state_none	No input state set.
hid_state_on	Key/button is currently pressed (logical on).
hid_state_off	Key/button is currently released (logical off).
hid_state_rising	Alias for hid_state_on; used to indicate a rising edge.
hid_state_falling	Alias for hid_state_off; used to indicate a falling edge.
hid_state_click	A single click event was generated.
hid_state_double_click	A double-click event was generated.
hid_state_triple_click	A triple-click event was generated.
hid_state_long_click	A long-press (long click) event was generated.
hid_state_repeat	A repeated key/button event (auto-repeat).
hid_state_function	Function key or mode modifier is active.
hid_state_caps_lock	Caps Lock state is active.
hid_state_num_lock	Num Lock state is active.
hid_state_scroll_lock	Scroll Lock state is active.
hid_state_left_shift	Left Shift modifier is active.
hid_state_right_shift	Right Shift modifier is active.
hid_state_left_meta	Left Meta (Command) modifier is active.
hid_state_right_meta	Right Meta (Command) modifier is active.
hid_state_left_alt	Left Option/Alt modifier is active.
hid_state_right_alt	Right Option/Alt modifier is active.
hid_state_left_control	Left Control modifier is active.
hid_state_right_control	Right Control modifier is active.
hid_state_left_windows	Left Windows/Meta modifier is active.
hid_state_right_windows	Right Windows/Meta modifier is active.
hid_state_shift	Convenience mask: either left or right Shift.
hid_state_meta	Convenience mask: either left or right Meta (Command).
hid_state_alt	Convenience mask: either left or right Alt (Option).
hid_state_control	Convenience mask: either left or right Control.
hid_state_windows	Convenience mask: either left or right Windows/Meta.

Definition at line 23 of file keycode.h.

             {
  hid_state_none = 0,       
  hid_state_on = (1 << 0),  
  hid_state_off = (1 << 1), 
  hid_state_rising = hid_state_on,   
  hid_state_falling = hid_state_off, 
  hid_state_click = (1 << 2),        
  hid_state_double_click = (1 << 3), 
  hid_state_triple_click = (1 << 4), 
  hid_state_long_click =
      (1 << 5), 
  hid_state_repeat = (1 << 6),   
  hid_state_function = (1 << 7), 
  hid_state_caps_lock = (1 << 8),    
  hid_state_num_lock = (1 << 9),     
  hid_state_scroll_lock = (1 << 10), 
  hid_state_left_shift = (1 << 11),  
  hid_state_right_shift = (1 << 12), 
  hid_state_left_meta = (1 << 13), 
  hid_state_right_meta =
      (1 << 14),                   
  hid_state_left_alt = (1 << 15),  
  hid_state_right_alt = (1 << 16), 
  hid_state_left_control = (1 << 17),  
  hid_state_right_control = (1 << 18), 
  hid_state_left_windows = (1 << 19), 
  hid_state_right_windows =
      (1 << 20), 
  hid_state_shift = (hid_state_left_shift |
                     hid_state_right_shift), 
  hid_state_meta = (hid_state_left_meta |
                    hid_state_right_meta), 
  hid_state_alt = (hid_state_left_alt |
                   hid_state_right_alt), 
  hid_state_control = (hid_state_left_control |
                       hid_state_right_control), 
  hid_state_windows =
      (hid_state_left_windows |
       hid_state_right_windows), 
} hid_state_t;

Function Documentation

hid_event_free()

void hid_event_free

(

hid_event_t *

event

)

Free a HID event allocated internally by HID queue helpers.

Parameters

event

Event pointer to release.

For a one-shot (non-repeating) hid_register_timer() device, freeing its hid_event_type_timer event is also what finally deregisters the device - the timer itself already stopped when the event fired, but the hid_device_t pool slot is kept alive until this call, since event's device field must stay valid until the consumer is done with the event. No separate hid_deregister() call is needed for a one-shot timer; the device is already gone once this returns.

hid_event_queue_iostream()

bool hid_event_queue_iostream	(	hid_device_t *	device,
		sys_iostream_event_t	events
	)

Queue a stream-readiness HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
events	Readiness event(s) to publish - see sys_iostream_event_t.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_event_queue_keycode()

bool hid_event_queue_keycode	(	hid_device_t *	device,
		hid_state_t	state,
		uint16_t	keycode
	)

Queue a keycode-based HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
state	Input transition flags to apply (for example hid_state_on/hid_state_off).
keycode	HID keycode associated with the event.

Return values

true	Event queued successfully.
false	Queueing failed.

The helper applies state to the device-local HID state, then queues an event containing the resulting state snapshot.

hid_event_queue_metric_float()

bool hid_event_queue_metric_float	(	hid_device_t *	device,
		const char *	name,
		const char *	unit,
		float	value
	)

Queue a float metric HID event to a HID instance queue.

Parameters

device	HID device associated with the destination queue.
name	Metric name string.
unit	Metric unit string.
value	Metric value.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_event_queue_signal()

bool hid_event_queue_signal	(	hid_device_t *	device,
		sys_env_signal_t	signal
	)

Queue a signal HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
signal	Environment signal value to publish.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_event_queue_time()

bool hid_event_queue_time	(	hid_device_t *	device,
		const sys_date_t *	date
	)

Queue a time HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
date	Date/time to publish. Copied by value into the queued event - see hid_time_t.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_event_queue_touch()

bool hid_event_queue_touch	(	hid_device_t *	device,
		hid_state_t	state,
		pix_point_t	point,
		uint8_t	slot
	)

Queue a touch HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
state	Touch state flags for this event.
point	Touch coordinates in pixels.
slot	Touch slot index.

Return values

true	Event queued successfully.
false	Queueing failed.

Todo:

Not implemented yet - there is no .c definition for this function anywhere in src/picofuse/hid/, so linking any code that calls it will fail. There is also no touch-controller registration helper (a hid_register_touch()-style function) yet; a driver such as dev/ft6236.h or dev/stmpe610.h would presumably call this directly once it exists, the same way ADC/temperature drivers call hid_event_queue_metric_float().

hid_event_queue_usb()

bool hid_event_queue_usb	(	hid_device_t *	device,
		hw_usb_event_t	event,
		const hw_usb_device_t *	usb_device
	)

Queue a USB hotplug HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
event	USB hotplug event to publish (see hw_usb_event_t).
usb_device	Associated device, or NULL for the enumeration-complete marker. Copied by value into the queued event - see hid_usb_t.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_event_queue_wifi()

bool hid_event_queue_wifi	(	hid_device_t *	device,
		hw_wifi_event_t	event,
		const hw_wifi_network_t *	network
	)

Queue a Wi-Fi status HID event to the owning HID instance queue.

Parameters

device	HID device associated with the event.
event	Wi-Fi status event to publish (see hw_wifi_event_t).
network	Associated network info, or NULL if not applicable. Copied by value into the queued event - see hid_wifi_t.

Return values

true	Event queued successfully.
false	Queueing failed.

hid_state_to_string()

size_t hid_state_to_string	(	hid_state_t	state,
		char *	buf,
		size_t	buf_size
	)

Format a HID state bitmask as a "|"-separated list of active flag names (for example "on|left_shift").

Only atomic flags are tested (for example hid_state_left_shift), not the either-left-or-right convenience masks (hid_state_shift and similar), since those would otherwise be reported redundantly alongside whichever side is actually set. Writes "none" when no flags are set.

Parameters

state	State bitmask to format.
buf	Destination buffer.
buf_size	Size of buf in bytes.

Returns

Number of characters that would have been written to buf, not counting the null terminator, same truncation semantics as sys_sprintf().