![]() |
|
Uniot Core
|
| 0.9.0 |
Main API class for the Uniot IoT platform. More...
#include <Uniot.h>
Public Types | |
| using | TimerId = uint32_t |
| Type for timer identifiers. | |
| using | ListenerId = uint32_t |
| Type for event listener identifiers. | |
Public Member Functions | |
| UniotCore () | |
| Construct a new UniotCore instance. | |
| void | configWiFiResetButton (uint8_t pinBtn, uint8_t activeLevelBtn=LOW, bool registerLispBtn=true) |
| Configure WiFi reset button. | |
| void | configWiFiStatusLed (uint8_t pinLed, uint8_t activeLevelLed=HIGH) |
| Configure WiFi status LED. | |
| void | configWiFiResetOnReboot (uint8_t maxRebootCount=UNIOT_WIFI_REBOOT_RESET_COUNT, uint32_t rebootWindowMs=UNIOT_WIFI_REBOOT_WINDOW_MS) |
| Configure automatic WiFi reset on repeated reboots. | |
| void | configWiFiCredentials (const String &ssid, const String &password="") |
| Configure WiFi network credentials. | |
| void | configUser (const String &user) |
| Configure user identification. | |
| void | addCustomPage (const String &path, const uint8_t *gzData, size_t gzLen, const String &label="", const char *contentType="text/html") |
| Register a custom gzipped page on the configuration portal. | |
| void | addCustomRoute (const String &path, ArRequestHandlerFunction handler) |
| Register a custom HTTP GET route on the configuration portal. | |
| void | addCustomRoute (const String &path, WebRequestMethodComposite method, ArRequestHandlerFunction handler) |
| Register a custom HTTP route on the configuration portal. | |
| void | addMQTTDevice (uniot::MQTTDevice &device) |
| Register a user-defined MQTT device with the platform. | |
| void | enablePeriodicDateSave (uint32_t periodSeconds=5 *60) |
| Enable periodic saving of date/time information. | |
| void | addLispPrimitive (Primitive *primitive) |
| Add a custom primitive to the Lisp interpreter. | |
| void | setLispEventInterceptor (uniot::LispEventInterceptor interceptor) |
| Set event interceptor for Lisp interpreter. | |
| void | setLispStartHook (uniot::LispStartHook hook) |
| Set the hook called when a Lisp script starts. | |
| void | setLispStopHook (uniot::LispStopHook hook) |
| Set the hook called when a Lisp script stops. | |
| void | publishLispEvent (const String &eventID, int32_t value) |
| Publish an event to the Lisp interpreter. | |
| template<typename... Pins> | |
| void | registerLispDigitalOutput (uint8_t first, Pins... pins) |
| Register GPIO pins as digital outputs for Lisp access. | |
| template<typename... Pins> | |
| void | registerLispDigitalInput (uint8_t first, Pins... pins) |
| Register GPIO pins as digital inputs for Lisp access. | |
| template<typename... Pins> | |
| void | registerLispAnalogInput (uint8_t first, Pins... pins) |
| Register GPIO pins as analog inputs for Lisp access. | |
| template<typename... Pins> | |
| void | registerLispAnalogOutput (uint8_t first, Pins... pins) |
| Register GPIO pins as analog outputs for Lisp access. | |
| bool | registerLispButton (uniot::Button *button, uint32_t id=FOURCC(_btn)) |
| Register a button object with the Lisp interpreter. | |
| int | addLispButton (uint8_t pin, uint8_t activeLevel=LOW, uint32_t id=FOURCC(_btn), uniot::Button::ButtonCallback callback=nullptr) |
| Create a button on a pin and expose it to Lisp scripts. | |
| void | resetLispButtons () |
| Clear pending clicks and long presses on every Lisp button. | |
| bool | registerLispObject (const String &primitiveName, uniot::RecordPtr link, uint32_t id=FOURCC(____)) |
| Register a generic object with the Lisp interpreter. | |
| TimerId | setInterval (std::function< void()> callback, uint32_t intervalMs, short times=0) |
| Create a repeating timer. | |
| TimerId | setTimeout (std::function< void()> callback, uint32_t timeoutMs) |
| Create a one-shot timer. | |
| TimerId | setImmediate (std::function< void()> callback) |
| Execute a callback on the next scheduler cycle. | |
| bool | cancelTimer (TimerId id) |
| Cancel an active timer. | |
| bool | isTimerActive (TimerId id) |
| Check if a timer is currently active. | |
| int | getActiveTimersCount () const |
| Get the number of active timers. | |
| uniot::TaskScheduler::TaskPtr | createTask (const char *name, uniot::SchedulerTask::SchedulerTaskCallback callback) |
| Create a named task for custom scheduling. | |
| template<typename... Topics> | |
| ListenerId | addSystemListener (std::function< void(unsigned int, int)> callback, unsigned int firstTopic, Topics... otherTopics) |
| Add a system event listener. | |
| bool | removeSystemListener (ListenerId id) |
| Remove a system event listener. | |
| template<typename... Topics> | |
| size_t | removeSystemListeners (unsigned int firstTopic, Topics... otherTopics) |
| Remove all listeners for specific topics. | |
| bool | isSystemListenerActive (ListenerId id) |
| Check if a system listener is active. | |
| int | getActiveListenersCount () const |
| Get the number of active event listeners. | |
| void | emitSystemEvent (unsigned int topic, int message) |
| Emit a system event. | |
| ListenerId | addWifiStatusLedListener (std::function< void(bool)> callback) |
| Add a WiFi status LED listener. | |
| void | begin (uint32_t eventBusTaskPeriod=10) |
| Initialize and start the Uniot platform. | |
| void | loop () |
| Process scheduled tasks and events. | |
| uniot::AppKit & | getAppKit () |
| Get access to the application kit. | |
| uniot::CoreEventBus & | getEventBus () |
| Get access to the event bus. | |
| uniot::TaskScheduler & | getScheduler () |
| Get access to the task scheduler. | |
Static Public Attributes | |
| static constexpr TimerId | INVALID_TIMER_ID = 0 |
| Invalid timer ID constant. | |
| static constexpr ListenerId | INVALID_LISTENER_ID = 0 |
| Invalid listener ID constant. | |
| static constexpr uint8_t | REBOOT_RESET_DISABLED = UINT8_MAX |
| Sentinel value for configWiFiResetOnReboot(): disables reboot-reset entirely. | |
Main API class for the Uniot IoT platform.
This class provides a comprehensive interface for building IoT applications with minimal boilerplate code. It orchestrates all platform subsystems including networking, scheduling, scripting, and hardware management.
The UniotCore class implements a singleton-like pattern through the global Uniot instance, providing immediate access to platform capabilities without complex initialization procedures.
Architecture overview:
| using UniotCore::ListenerId = uint32_t |
Type for event listener identifiers.
| using UniotCore::TimerId = uint32_t |
Type for timer identifiers.
|
inline |
|
inline |
Register a custom gzipped page on the configuration portal.
| path | URL path to serve the page on (e.g. "/app") |
| gzData | Pointer to the gzipped page data |
| gzLen | Length of the gzipped data in bytes |
| label | Button label shown in the portal UI (empty hides the button) |
| contentType | MIME content type (default: "text/html") |
Serves a user-supplied embedded page from the captive portal server, and reports it to the configuration UI so it can link to the page. Must be called before begin().
Typically used with a C array generated from a gzipped HTML file:
|
inline |
Register a custom HTTP GET route on the configuration portal.
| path | URL path for the route (e.g. "/api/data") |
| handler | Callback invoked to handle the request |
Suitable for sensor data APIs and other endpoints that should not appear as a navigation button. Must be called before begin().
|
inline |
Register a custom HTTP route on the configuration portal.
| path | URL path for the route (e.g. "/api/data") |
| method | HTTP method(s) to accept (e.g. HTTP_GET, HTTP_POST, HTTP_ANY) |
| handler | Callback invoked to handle the request |
Must be called before begin().
|
inline |
Create a button on a pin and expose it to Lisp scripts.
| pin | GPIO pin the button is connected to |
| activeLevel | Logic level while the button is pressed (LOW or HIGH) |
| id | FOURCC identifier shown for the button in the device's registers (default: _btn) |
| callback | Optional handler for CLICK and LONG_PRESS, run from the scheduler |
| int | The button's index, as scripts pass it to bclicked, or -1 if it could not be registered |
Everything a button needs, in one call: the Button is created and owned here, polled every 100 ms, and linked into the bclicked register. A long press is 3 seconds, the same as the WiFi reset button. For a button with other timing, create it yourself and use registerLispButton().
The index is the button's position in the bclicked register, so it follows registration order. The WiFi reset button from configWiFiResetButton() is linked during begin(), so buttons added before begin() come before it and buttons added after it follow. Adding buttons after begin(), at the end of setup(), keeps the reset button at index 0.
Add buttons in setup(). Registers are reported to the platform when MQTT connects, which happens once loop() is running, so a button added later is not reported until the device reconnects.
The pin gets the internal pull its active level needs: a pull-up for LOW, a pull-down for HIGH. Pins without that pull need an external resistor; see Button::applyPinMode().
|
inline |
Add a custom primitive to the Lisp interpreter.
| primitive | Pointer to the primitive implementation |
Extends the embedded Lisp interpreter with custom functionality. Primitives provide the bridge between Lisp scripts and hardware or application-specific operations.
|
inline |
Register a user-defined MQTT device with the platform.
| device | The MQTTDevice instance to register |
Adds the device to the MQTT subsystem and synchronizes its subscriptions, so it can publish to and receive from its own topics.
|
inline |
Add a system event listener.
| callback | Function to call when events occur |
| firstTopic | First event topic to listen for |
| otherTopics | Additional event topics to listen for |
| ListenerId | Listener identifier for management operations |
Registers a callback function to receive system events from multiple topics. The callback receives the topic and message for event handling.
|
inline |
Add a WiFi status LED listener.
| callback | Function to call when LED status changes |
| ListenerId | Listener identifier for management operations |
Convenience method for listening to WiFi status LED events. The callback receives a boolean indicating the desired LED state.
These events come from the network controller, which exists only once one of the configWiFi* methods has asked for it. A device with no button and no LED – a bulb driving its own light as the indicator, say – still gets one from configWiFiResetOnReboot(). Without any of them this callback never fires; the missing controller is reported by AppKit when the scheduler is populated.
|
inline |
Initialize and start the Uniot platform.
| eventBusTaskPeriod | Event bus processing interval in milliseconds |
Initializes all platform subsystems, applies configuration, and starts the main event loop. This method should be called once during setup.
|
inline |
Cancel an active timer.
| id | Timer identifier returned by set* functions |
| bool | true if timer was found and canceled, false otherwise |
Stops and removes an active timer, preventing further executions. Similar to JavaScript's clearInterval() and clearTimeout() functions.
|
inline |
Configure user identification.
| user | User identifier string for device association |
Sets the user ID for device identification and association purposes. This identifier is used for device management and tracking within the Uniot ecosystem.
|
inline |
Configure WiFi network credentials.
| ssid | Network SSID to connect to |
| password | Network password (empty for open networks) |
Sets the WiFi credentials for automatic network connection. The credentials are validated and stored persistently for use across device reboots.
|
inline |
Configure WiFi reset button.
| pinBtn | GPIO pin number for the reset button |
| activeLevelBtn | Active logic level for button (LOW or HIGH) |
| registerLispBtn | Whether to register button with Lisp interpreter |
Configures a hardware button for WiFi network reset functionality. The button provides both manual reconnection (single press) and configuration reset (multiple rapid presses followed by long press).
With registerLispBtn, the button is linked into the bclicked register during begin(). Buttons added with addLispButton() before begin() therefore come before it; add them after begin(), still in setup(), to keep this button at index 0.
|
inline |
Configure automatic WiFi reset on repeated reboots.
| maxRebootCount | Maximum reboots before triggering configuration reset, or UniotCore::REBOOT_RESET_DISABLED to opt out entirely. Defaults to UNIOT_WIFI_REBOOT_RESET_COUNT. |
| rebootWindowMs | Time window for counting reboots in milliseconds. Defaults to UNIOT_WIFI_REBOOT_WINDOW_MS. Ignored when maxRebootCount is REBOOT_RESET_DISABLED. |
Enables automatic configuration reset when the device reboots repeatedly within a specified time window. This provides a recovery mechanism for devices that become unreachable due to network configuration issues.
Pass REBOOT_RESET_DISABLED to completely suppress this behaviour: no reboot counter is stored to or read from flash, and the network configuration is never reset automatically.
Called with no arguments it is also the way to ask for a network controller on a device that configures neither a button nor a status LED: the controller is what emits the WiFi status events, and on such a device reboot-reset is the only path back from bad credentials.
|
inline |
Configure WiFi status LED.
| pinLed | GPIO pin number for the status LED |
| activeLevelLed | Active logic level for LED (LOW or HIGH) |
Configures a hardware LED for visual indication of WiFi connection status. The LED provides different blinking patterns for various connection states:
|
inline |
Create a named task for custom scheduling.
| name | Optional name for the task (for debugging) |
| callback | Function to execute when task runs |
| TaskPtr | Pointer to the created task for manual management |
Creates a task that can be manually scheduled and managed. Provides direct access to the underlying task scheduler for advanced use cases.
|
inline |
Emit a system event.
| topic | Event topic identifier |
| message | Event message identifier |
Broadcasts an event to all registered listeners on the specified topic. Events are processed asynchronously through the event bus.
|
inline |
Enable periodic saving of date/time information.
| periodSeconds | Interval between saves in seconds (0 to disable) |
Configures automatic persistence of date/time information to prevent time loss during device reboots. Useful for maintaining accurate timestamps when NTP synchronization is not always available.
|
inline |
Get the number of active event listeners.
| int | Count of currently active listeners |
Returns the current number of active event listeners for monitoring and debugging purposes.
|
inline |
Get the number of active timers.
| int | Count of currently active timers |
Returns the current number of active timers for monitoring and debugging purposes.
|
inline |
Get access to the application kit.
| AppKit& | Reference to the application kit instance |
Provides access to lower-level platform functionality for advanced use cases that require direct subsystem interaction.
|
inline |
Get access to the event bus.
| CoreEventBus& | Reference to the event bus instance |
Provides direct access to the event bus for advanced event handling and custom event types.
|
inline |
Get access to the task scheduler.
| TaskScheduler& | Reference to the scheduler instance |
Provides direct access to the task scheduler for advanced scheduling requirements and custom task management.
|
inline |
Check if a system listener is active.
| id | Listener identifier to check |
| bool | true if listener exists and is active, false otherwise |
Determines whether a system event listener is currently registered and active.
|
inline |
Check if a timer is currently active.
| id | Timer identifier to check |
| bool | true if timer exists and is active, false otherwise |
Determines whether a timer is currently scheduled for execution.
|
inline |
Process scheduled tasks and events.
Executes one iteration of the main scheduler loop. This method should be called continuously from the main program loop to ensure proper system operation.
|
inline |
Publish an event to the Lisp interpreter.
| eventID | Unique identifier for the event |
| value | Numeric value associated with the event |
Sends events from the application to the Lisp interpreter, enabling bidirectional communication and script-driven responses to system events.
|
inline |
Register GPIO pins as analog inputs for Lisp access.
| first | First GPIO pin number |
| pins | Additional GPIO pin numbers |
Makes specified GPIO pins available to the Lisp interpreter as analog input pins, enabling script-based analog sensor reading.
Register inputs before begin(). Registering sets the pins to plain INPUT, which clears any pull; begin() gives a button on one of these pins its pull back.
|
inline |
Register GPIO pins as analog outputs for Lisp access.
| first | First GPIO pin number |
| pins | Additional GPIO pin numbers |
Makes specified GPIO pins available to the Lisp interpreter as analog output pins (PWM), enabling script-based analog control.
|
inline |
Register a button object with the Lisp interpreter.
| button | Pointer to the button instance |
| id | FOURCC identifier for the button (default: _btn) |
| bool | true if registration was successful, false otherwise |
Makes a button object available to the Lisp interpreter, enabling script-based button event handling and state monitoring.
|
inline |
Register GPIO pins as digital inputs for Lisp access.
| first | First GPIO pin number |
| pins | Additional GPIO pin numbers |
Makes specified GPIO pins available to the Lisp interpreter as digital input pins, enabling script-based sensor reading.
Register inputs before begin(). Registering sets the pins to plain INPUT, which clears any pull; begin() gives a button on one of these pins its pull back.
|
inline |
Register GPIO pins as digital outputs for Lisp access.
| first | First GPIO pin number |
| pins | Additional GPIO pin numbers |
Makes specified GPIO pins available to the Lisp interpreter as digital output pins, enabling script-based hardware control.
|
inline |
Register a generic object with the Lisp interpreter.
| primitiveName | Name of the primitive to associate with the object |
| link | Pointer to the object to register |
| id | FOURCC identifier for the object |
| bool | true if registration was successful, false otherwise |
Provides a generic mechanism for making application objects available to the Lisp interpreter through named primitives.
|
inline |
Remove a system event listener.
| id | Listener identifier returned by addSystemListener |
| bool | true if listener was found and removed, false otherwise |
Unregisters a system event listener and cleans up associated resources.
|
inline |
Remove all listeners for specific topics.
| firstTopic | First topic to remove listeners from |
| otherTopics | Additional topics to remove listeners from |
| size_t | Number of listeners removed |
Removes all active listeners that are subscribed to any of the specified topics. Useful for bulk cleanup operations.
|
inline |
Clear pending clicks and long presses on every Lisp button.
A press that no script has read stays pending for up to 10 seconds, so a script started within that window can read a press made before it existed. Call this from a start hook to drop those presses:
Covers every button in the bclicked register, however it was added. The WiFi reset button's own behaviour is unaffected: it works from its callbacks, not these flags.
|
inline |
Execute a callback on the next scheduler cycle.
| callback | Function to execute immediately |
| TimerId | Timer identifier for management operations |
Schedules a callback for immediate execution on the next scheduler cycle. Similar to JavaScript's setImmediate() function.
|
inline |
Create a repeating timer.
| callback | Function to execute on timer expiration |
| intervalMs | Interval between executions in milliseconds |
| times | Number of times to execute (0 for infinite) |
| TimerId | Timer identifier for management operations |
Creates a timer that executes the callback function at regular intervals. Similar to JavaScript's setInterval() function.
|
inline |
Set event interceptor for Lisp interpreter.
| interceptor | Function to intercept and process Lisp events |
Configures a callback function to intercept events generated by the Lisp interpreter, enabling custom event processing and application-specific behavior.
|
inline |
Set the hook called when a Lisp script starts.
| hook | Callback receiving why the script started |
Runs after the interpreter is built and its primitives are registered, but before the script is evaluated, so a peripheral brought up here is ready for the first pass. The reason says where the script came from: LispStartReason::Restored for one loaded from flash at boot, LispStartReason::Received for one delivered over MQTT.
Keep the hook short – see setLispStopHook() for why that matters most there.
|
inline |
Set the hook called when a Lisp script stops.
| hook | Callback receiving why the script stopped |
Runs before the interpreter is destroyed, whichever way the script ended: Completed (it ran to the end, or a finite task used up its passes), Replaced (a new script took its place), Cleared (an empty script arrived, meaning run nothing) or Failed (a Lisp error tore the machine down).
Both hooks run synchronously, so keep them short and move heavy work out with setImmediate(), which runs it on the next scheduler pass instead:
This matters most for LispStopReason::Failed. That case is reached from the interpreter's error printer while lisp_eval() is still unwinding, on a stack already near the limit UNIOT_LISP_MAX_EVAL_STACK guards – do only what is needed to leave the hardware in a safe state, and defer everything else.
|
inline |
Create a one-shot timer.
| callback | Function to execute after timeout |
| timeoutMs | Delay before execution in milliseconds |
| TimerId | Timer identifier for management operations |
Creates a timer that executes the callback function once after the specified delay. Similar to JavaScript's setTimeout() function.
|
staticconstexpr |
Invalid listener ID constant.
|
staticconstexpr |
Invalid timer ID constant.
|
staticconstexpr |
Sentinel value for configWiFiResetOnReboot(): disables reboot-reset entirely.
Pass this as maxRebootCount to opt out of the automatic configuration-reset mechanism. No reboot counts are stored, read, or compared, and the device will never be force-reset due to repeated reboots.