File espos_sk.h¶

FileList > espos_sk > include > espos_sk.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"
#include "espos_sk_token_sm.h"
#include "espos_sk_parse.h"

Classes¶

Type	Name
struct	espos_sk_discovered_t
struct	espos_sk_ws_status_t

Public Types¶

Type	Name
enum	espos_sk_alert_t Raise or clear a SignalK notification under notifications.espos.LABEL.KEY (the device label and the condition key).
typedef void(*	espos_sk_put_cb_t PUT a value (JSON text) to a vessels.self path over the stream.
typedef esp_err_t(*	espos_sk_put_handler_t Handle a PUT the SERVER sends to this device: how a phone operates a switch.
typedef void(*	espos_sk_sub_cb_t Subscribe to values (and meta) of vessels.self paths.

Public Functions¶

Type	Name
const char *	espos_sk_client_id (void)
esp_err_t	espos_sk_declare_meta (const char * path, const char * meta_json, uint32_t period_ms)
esp_err_t	espos_sk_discover_now (void)
esp_err_t	espos_sk_flush (uint32_t timeout_ms) Send everything buffered and wait until the stream has drained, up to timeout_ms.
esp_err_t	espos_sk_forget_token (void)
esp_err_t	espos_sk_get_server (espos_sk_server_t * out) Copy the current server (host/port/self); ESP_ERR_NOT_FOUND if none.
esp_err_t	espos_sk_get_token (char * buf, size_t size) Copy the current usable token ("" if none).
esp_err_t	espos_sk_notify (const char * key, espos_sk_alert_t state, const char * message)
esp_err_t	espos_sk_publish_bool (const char * path, bool value)
esp_err_t	espos_sk_publish_json (const char * path, const char * value_json) value_json is a complete JSON value (object, array, null, …).
esp_err_t	espos_sk_publish_number (const char * path, double value) Publish a value for a SignalK path (vessels.self).
esp_err_t	espos_sk_publish_string (const char * path, const char * value)
esp_err_t	espos_sk_put (const char * path, const char * value_json, espos_sk_put_cb_t cb, void * arg)
esp_err_t	espos_sk_put_handler_register (const char * path, espos_sk_put_handler_t cb, void * arg)
esp_err_t	espos_sk_put_handler_unregister (const char * path)
esp_err_t	espos_sk_put_respond (const char * request_id, const char * state, int status_code, const char * message) Answer a PUT request.
void	espos_sk_report_cert_error (const char * reason) Report that the server's TLS certificate was refused: the token machine enters `cert_error` , keeps the token (the credential is fine, the transport is not) and retries on a flat 60 s.
void	espos_sk_report_unauthorized (void) Report that some SK call was rejected with 401/403 (M4 uses this).
esp_err_t	espos_sk_request_now (void)
esp_err_t	espos_sk_send_raw (const char * json) Send an arbitrary text frame on the stream (e.g.
esp_err_t	espos_sk_servers_json (char ** out_json) Discovered servers as JSON array document {"servers":[...]} (malloc'ed).
esp_err_t	espos_sk_set_app_name (const char * name) Name the device in the server's access-request list.
esp_err_t	espos_sk_set_token (const char * token)
esp_err_t	espos_sk_start (void) Start the SignalK task: loads config + persistent state, runs discovery and the token machine, registers the /api/v1/sk endpoints.
esp_err_t	espos_sk_status_json (char ** out_json) Status document of docs/rest-api.md (malloc'ed JSON).
esp_err_t	espos_sk_stop (void)
int	espos_sk_subscribe (const char * pattern, uint32_t period_ms, espos_sk_sub_cb_t cb, void * arg)
esp_err_t	espos_sk_unsubscribe (int handle)
esp_err_t	espos_sk_ws_get_status (espos_sk_ws_status_t * out)

Macros¶

Type	Name
define	ESPOS_SK_MAX_META `32` Declare metadata for a NON-standard path (never for spec paths — the server knows those).
define	ESPOS_SK_MAX_PUT_HANDLERS `16`
define	ESPOS_SK_MAX_SERVERS `12`
define	ESPOS_SK_MAX_SUBS `48`
define	ESPOS_SK_PUT_PENDING `1` Returned by a handler that will answer later via espos_sk_put_respond() .

Public Types Documentation¶

enum espos_sk_alert_t¶

Raise or clear a SignalK notification under notifications.espos.LABEL.KEY (the device label and the condition key).

enum espos_sk_alert_t {
    ESPOS_SK_ALERT_NORMAL = 0,
    ESPOS_SK_ALERT_WARN,
    ESPOS_SK_ALERT_ALARM
};

For conditions the device knows about and an operator would want to see: memory pressure, an overheating chip, a service the firmware depends on having gone away. These otherwise surface as a device that has quietly stopped doing its job, which is indistinguishable from a hardware fault from the outside and is the expensive kind of problem to diagnose.

Notifications are level-triggered and idempotent: raising the same state and message twice sends one delta, so a caller may poll and re-raise freely. Passing ESPOS_SK_ALERT_NORMAL clears the condition.

key is a short stable identifier ("lowMemory", "wakeService"), not a sentence it becomes part of the path, and the path is what a rule or a dashboard keys on. message is the human-readable half and may change without re-notifying.

Thread-safe; never blocks. Buffered like any other delta while offline.

typedef espos_sk_put_cb_t¶

PUT a value (JSON text) to a vessels.self path over the stream.

typedef void(* espos_sk_put_cb_t) (const char *request_id, const char *state, int status_code, const char *message, void *arg);

cb (may be NULL) gets the server's response — state COMPLETED/FAILED with statusCode — or state "TIMEOUT" after 10 s. Queued if the stream is momentarily busy; ESP_ERR_INVALID_STATE when not connected, ESP_ERR_NO_MEM when 8 requests are already in flight.

typedef espos_sk_put_handler_t¶

Handle a PUT the SERVER sends to this device: how a phone operates a switch.

typedef esp_err_t(* espos_sk_put_handler_t) (const char *path, const char *value_json, void *arg);

The counterpart of espos_sk_put(), which goes the other way.

The server only routes a PUT to a device it has seen publish that path, so a controllable path must be published at least once (any espos_sk_publish_*) before a request can arrive signalk-server keys its route on the (path, $source) pairs it has observed on this connection.

value_json is the requested value as JSON text ("true", "0.5", "\"auto\"", "null"). Return: ESP_OK applied answered COMPLETED 200, ESP_ERR_INVALID_ARG the value made no sense COMPLETED 400, anything else COMPLETED 502. Answer later instead by returning ESPOS_SK_PUT_PENDING and calling espos_sk_put_respond() when the work is done; the server waits 60 s.

cb runs on the stream task: copy what you need, do not block, and do not call back into espos_sk_* calls that wait on the stream. Publishing the new value is the normal thing to do and is safe (it never blocks).

A path with no handler is answered COMPLETED 405, which is what signalk-server itself replies for an unhandled path (src/put.ts) and what a client expects.

typedef espos_sk_sub_cb_t¶

Subscribe to values (and meta) of vessels.self paths.

typedef void(* espos_sk_sub_cb_t) (const espos_sk_update_t *u, void *arg);

pattern is an exact path or a family: "notifications.*", "environment.*", "*". period_ms is the server-side rate hint (0 = 1000). cb runs on the stream task with strings valid only during the call — copy, do not block, do not call espos_sk_* that could wait on the stream. Meta arrives as items with meta_json set (stream opened with sendMeta=all). Subscriptions survive reconnects and are (re)sent after every hello. Returns a handle > 0, or <0 (-ESP_ERR_NO_MEM style) when the table is full.

Public Functions Documentation¶

function espos_sk_client_id¶

const char * espos_sk_client_id (
    void
)

function espos_sk_declare_meta¶

esp_err_t espos_sk_declare_meta (
    const char * path,
    const char * meta_json,
    uint32_t period_ms
)

function espos_sk_discover_now¶

esp_err_t espos_sk_discover_now (
    void
)

function espos_sk_flush¶

Send everything buffered and wait until the stream has drained, up to timeout_ms.

esp_err_t espos_sk_flush (
    uint32_t timeout_ms
)

The prerequisite for deep sleep: a delta published a millisecond before esp_deep_sleep_start() is otherwise still sitting in the batch buffer when the radio goes down.

Returns ESP_OK when nothing is left to send, ESP_ERR_TIMEOUT when the deadline passed with data still pending, ESP_ERR_INVALID_STATE when the stream is not connected (nothing can drain, so the caller should not wait). Blocks the calling task; never call it from the stream task or a subscription callback.

A message being written counts as pending until the write returns, so ESP_OK means every message was handed to the socket. It does not mean the server acknowledged it: on a live link the TCP stack sends within milliseconds, and a caller about to cut the radio should allow that.

function espos_sk_forget_token¶

esp_err_t espos_sk_forget_token (
    void
)

function espos_sk_get_server¶

Copy the current server (host/port/self); ESP_ERR_NOT_FOUND if none.

esp_err_t espos_sk_get_server (
    espos_sk_server_t * out
)

function espos_sk_get_token¶

Copy the current usable token ("" if none).

esp_err_t espos_sk_get_token (
    char * buf,
    size_t size
)

Thread-safe.

function espos_sk_notify¶

esp_err_t espos_sk_notify (
    const char * key,
    espos_sk_alert_t state,
    const char * message
)

function espos_sk_publish_bool¶

esp_err_t espos_sk_publish_bool (
    const char * path,
    bool value
)

function espos_sk_publish_json¶

value_json is a complete JSON value (object, array, null, …).

esp_err_t espos_sk_publish_json (
    const char * path,
    const char * value_json
)

function espos_sk_publish_number¶

Publish a value for a SignalK path (vessels.self).

esp_err_t espos_sk_publish_number (
    const char * path,
    double value
)

Values are batched (sk.batch_ms), buffered while offline and streamed over the WebSocket. Thread-safe; never blocks.

function espos_sk_publish_string¶

esp_err_t espos_sk_publish_string (
    const char * path,
    const char * value
)

function espos_sk_put¶

esp_err_t espos_sk_put (
    const char * path,
    const char * value_json,
    espos_sk_put_cb_t cb,
    void * arg
)

function espos_sk_put_handler_register¶

esp_err_t espos_sk_put_handler_register (
    const char * path,
    espos_sk_put_handler_t cb,
    void * arg
)

function espos_sk_put_handler_unregister¶

esp_err_t espos_sk_put_handler_unregister (
    const char * path
)

function espos_sk_put_respond¶

Answer a PUT request.

esp_err_t espos_sk_put_respond (
    const char * request_id,
    const char * state,
    int status_code,
    const char * message
)

Only needed after a handler returned ESPOS_SK_PUT_PENDING every other outcome is answered automatically.

state is "COMPLETED" or "PENDING": signalk-server accepts nothing else on this path (src/interfaces/ws.ts, isWsRequestReply) and silently drops a reply carrying anything else, which reads as a request that timed out 60 s later. A failure is COMPLETED with a 4xx/5xx statusCode, not a "FAILED" state.

Thread-safe; may be called from any task. ESP_ERR_INVALID_STATE when the stream is not connected.

function espos_sk_report_cert_error¶

Report that the server's TLS certificate was refused: the token machine enters cert_error , keeps the token (the credential is fine, the transport is not) and retries on a flat 60 s.

void espos_sk_report_cert_error (
    const char * reason
)

reason is the sentence an operator reads; NULL for a generic one. Thread-safe, queued to the SK task.

function espos_sk_report_unauthorized¶

Report that some SK call was rejected with 401/403 (M4 uses this).

void espos_sk_report_unauthorized (
    void
)

function espos_sk_request_now¶

esp_err_t espos_sk_request_now (
    void
)

function espos_sk_send_raw¶

Send an arbitrary text frame on the stream (e.g.

esp_err_t espos_sk_send_raw (
    const char * json
)

an inbound delta the server should ingest as-is). ESP_ERR_INVALID_STATE when not connected.

function espos_sk_servers_json¶

Discovered servers as JSON array document {"servers":[...]} (malloc'ed).

esp_err_t espos_sk_servers_json (
    char ** out_json
)

function espos_sk_set_app_name¶

Name the device in the server's access-request list.

esp_err_t espos_sk_set_app_name (
    const char * name
)

The default description is "<name> <hostname>" when sk.description is empty; without a name it is "espOS <hostname>", which tells an operator approving five requests nothing. espos_start() passes the application name. Takes effect on the next configuration load (before espos_sk_start(), or a config change). Copies at most 32 characters; ESP_ERR_INVALID_ARG on NULL.

function espos_sk_set_token¶

esp_err_t espos_sk_set_token (
    const char * token
)

function espos_sk_start¶

Start the SignalK task: loads config + persistent state, runs discovery and the token machine, registers the /api/v1/sk endpoints.

esp_err_t espos_sk_start (
    void
)

Needs espos_config, espos_httpd and (on device) espos_wifi to be started.

function espos_sk_status_json¶

Status document of docs/rest-api.md (malloc'ed JSON).

esp_err_t espos_sk_status_json (
    char ** out_json
)

function espos_sk_stop¶

esp_err_t espos_sk_stop (
    void
)

function espos_sk_subscribe¶

int espos_sk_subscribe (
    const char * pattern,
    uint32_t period_ms,
    espos_sk_sub_cb_t cb,
    void * arg
)

function espos_sk_unsubscribe¶

esp_err_t espos_sk_unsubscribe (
    int handle
)

function espos_sk_ws_get_status¶

esp_err_t espos_sk_ws_get_status (
    espos_sk_ws_status_t * out
)

Macro Definition Documentation¶

define ESPOS_SK_MAX_META¶

Declare metadata for a NON-standard path (never for spec paths — the server knows those).

#define ESPOS_SK_MAX_META `32`

meta_json is the full meta object, e.g. {"units":"Hz","description":"…"}. period_ms > 0 adds "timeout" (in seconds, 2.5× the period) as the one field the device really owns. Reconciled on every (re)connect: GET the server's meta, PUT only if it is empty — server-side edits win. Up to ESPOS_SK_MAX_META entries.

define ESPOS_SK_MAX_PUT_HANDLERS¶

#define ESPOS_SK_MAX_PUT_HANDLERS `16`

define ESPOS_SK_MAX_SERVERS¶

#define ESPOS_SK_MAX_SERVERS `12`

define ESPOS_SK_MAX_SUBS¶

#define ESPOS_SK_MAX_SUBS `48`

define ESPOS_SK_PUT_PENDING¶

Returned by a handler that will answer later via espos_sk_put_respond() .

#define ESPOS_SK_PUT_PENDING `1`

The documentation for this class was generated from the following file espos_sk/include/espos_sk.h