Startup abstraction layer#

Above the standard layer, only two functions are added: pull(), and call().

No other elements will be added, so in order to provide a sandbox in a minimal way, you can simply remove these two functions.

The abstraction layer is event-based; all information is provided through events initially piled up, that help building the picture of what the computer’s physical system resembles.

Event interfaces#

All events are provided as tables with no additional metadata. These classes represent the properties present in such tables, and their types and roles.

class Event#

An event on the component abstraction, as returned by pull(). Note that attributes include, but are not limited to the list provided below.

type: string#: Type of the event, to be used as a discriminator.

class BusEvent: Event #

Event raised when an event occurs on a bus, that does not concern a device directly.

id: number#: Numeric identifier of the bus to which the event applies.

class DeviceEvent: Event #

Event raised when an event occurs on a device.

id: number#: Numeric identifier of the component to which the event applies.

Bus events#

class BusAttachEvent: BusEvent #

Event raised when a new bus is attached.

type: string#: Set to "bus_attach".

bus: number | nil#: Identifier of the bus to which the bus is attached.

bus_type: string#: Type of the bus, as documented in Bus reference.

class BusDetachEvent: BusEvent #

Event raised when a bus is detached.

This event can only be raised if no device nor bus is still attached to the bus. If this happens, it is an incorrect behaviour from the startup, and should be reported and fixed.

type: string#: Set to "bus_detach".

Device events#

class DeviceAttachEvent: DeviceEvent #

Event raised when a device is attached.

type: string#: Set to "device_attach".

bus: number#: Numeric identifier of the bus to which the device has been attached to.

address: string#: The address the device was attached on the bus.

device_type: string#: Type of the device, as documented in Device reference.

class DeviceDetachEvent: DeviceEvent #

Event raised when a device is detached.

type: string#: Set to "device_detach".

Operations#

pull(timeout_sec)#

Pull the next event out of the queue, while waiting for timeout_sec seconds at a maximum.

Note

Fractional seconds are allowed and will be fulfilled within the underlying platform’s capabilities.

If timeout_sec is lesser or equal to 0, the function will return immediately with an event if available, or with nil otherwise.

Note

This function can also be used to sleep, in a power-saving effort. Therefore, if all your processes are either awaiting an external event or other processes, it is recommended to call this method with long timeouts.

If a timeout has occurred, the returned event will be nil.

Parameters:: timeout_sec (number) – Timeout in seconds.
Returns:: The next event in the queue, or nil.
Return type:: Event

call(id, name, ...)#

Call the method identified by its name name on the component which the identifier is id with the given arguments.

Parameters:

id (number) – Identifier of the component of which to call the method.
name (string) – The name of the method to call.

Returns:

The raw return value of the method, or nil if the method doesn’t exist on the given peripheral.