| title | Plugin Capabilities |
|---|
Declare required capabilities in package.json:
| Capability | Description | Status |
|---|---|---|
dataRead |
Read Signal K data model | Supported |
dataWrite |
Emit delta messages | Supported |
storage |
Write to VFS (vfs-only) |
Supported |
httpEndpoints |
Register custom HTTP endpoints | Supported |
network |
HTTP requests (via as-fetch) | Supported (AssemblyScript only) |
putHandlers |
Register PUT handlers for vessel control | Supported |
rawSockets |
UDP socket access for radar, NMEA, etc. | Supported |
resourceProvider |
Serve Signal K resources | Supported |
weatherProvider |
Provide data to the Signal K Weather API | Supported |
radarProvider |
Provide radars to the Signal K Radar API | Supported |
bluetooth |
Bluetooth Low Energy via the BLE API | Supported |
serialPorts |
Serial port access | Planned |
AssemblyScript plugins can make HTTP requests using the as-fetch library integrated into the SDK.
Requirements:
- Plugin must declare
"network": truein manifest - Server must be running Node.js 18+ (for native fetch support)
- Import network functions from SDK
- Must add
"transform": ["as-fetch/transform"]toasconfig.jsonoptions - Must set
"exportRuntime": trueinasconfig.jsonoptions
A plugin checks hasNetworkCapability() from the SDK before making requests, then calls fetchSync from as-fetch/sync, which blocks the plugin until the response arrives. example-weather-plugin is a maintained example of the full pattern.
fetchSync relies on Asyncify, which the server drives only while the plugin is starting and while it serves weather and radar provider requests. Requests made from polling, delta, HTTP, PUT or resource handlers are not supported.
The response from fetchSync in as-fetch 2.1.4 always reports status 200, so ok is true even for an HTTP error such as 401. A request that gets no HTTP response at all, such as a DNS lookup or connection error, also resumes the plugin with status 200, and its body is empty. Validate the response body before using it, rather than relying on the status.
Build Configuration (asconfig.json):
For plugins using network capability:
{
"targets": {
"release": {
"outFile": "build/plugin.wasm",
"optimize": true,
"shrinkLevel": 2,
"runtime": "stub"
}
},
"options": {
"bindings": "esm",
"exportRuntime": true,
"transform": ["as-fetch/transform"]
}
}Manifest Configuration:
{
"name": "my-plugin",
"wasmCapabilities": {
"network": true
},
"dependencies": {
"@signalk/assemblyscript-plugin-sdk": "^0.2.0",
"as-fetch": "^2.1.4"
}
}The rawSockets capability enables direct UDP socket access for plugins that need to communicate with devices like:
- Marine radars (Navico, Raymarine, Furuno, Garmin)
- NMEA 0183 over UDP
- AIS receivers
- Other marine electronics using UDP multicast
Requirements:
- Plugin must declare
"rawSockets": truein manifest - Sockets are non-blocking (poll-based receive)
- Automatic cleanup when plugin stops
Manifest Configuration:
{
"name": "my-radar-plugin",
"wasmManifest": "plugin.wasm",
"wasmCapabilities": {
"rawSockets": true,
"dataWrite": true
}
}FFI Functions Available:
| Function | Signature | Description |
|---|---|---|
sk_udp_create |
(type: i32) -> i32 |
Create socket (0=udp4, 1=udp6). Returns socket_id or -1 |
sk_udp_bind |
(socket_id, port) -> i32 |
Bind to port (0=any). Returns 0 or -1 |
sk_udp_join_multicast |
(socket_id, addr_ptr, addr_len, iface_ptr, iface_len) -> i32 |
Join multicast group |
sk_udp_leave_multicast |
(socket_id, addr_ptr, addr_len, iface_ptr, iface_len) -> i32 |
Leave multicast group |
sk_udp_set_multicast_ttl |
(socket_id, ttl) -> i32 |
Set multicast TTL |
sk_udp_set_multicast_loopback |
(socket_id, enabled) -> i32 |
Enable/disable loopback |
sk_udp_set_broadcast |
(socket_id, enabled) -> i32 |
Enable/disable broadcast |
sk_udp_send |
(socket_id, addr_ptr, addr_len, port, data_ptr, data_len) -> i32 |
Send datagram |
sk_udp_recv |
(socket_id, buf_ptr, buf_max_len, addr_out_ptr, port_out_ptr) -> i32 |
Receive datagram (non-blocking) |
sk_udp_pending |
(socket_id) -> i32 |
Get number of buffered datagrams |
sk_udp_close |
(socket_id) -> void |
Close socket |
Rust Example:
#[link(wasm_import_module = "env")]
extern "C" {
fn sk_udp_create(socket_type: i32) -> i32;
fn sk_udp_bind(socket_id: i32, port: u16) -> i32;
fn sk_udp_join_multicast(
socket_id: i32,
addr_ptr: *const u8, addr_len: usize,
iface_ptr: *const u8, iface_len: usize
) -> i32;
fn sk_udp_recv(
socket_id: i32,
buf_ptr: *mut u8, buf_max_len: usize,
addr_out_ptr: *mut u8, port_out_ptr: *mut u16
) -> i32;
fn sk_udp_close(socket_id: i32);
}
// Example: Radar discovery
fn start_radar_locator() -> i32 {
// Create UDP socket
let socket_id = unsafe { sk_udp_create(0) }; // udp4
if socket_id < 0 {
return -1;
}
// Bind to radar discovery port
if unsafe { sk_udp_bind(socket_id, 6878) } < 0 {
return -1;
}
// Join radar multicast group
let group = "239.254.2.0";
let iface = "";
if unsafe { sk_udp_join_multicast(socket_id, group.as_ptr(), group.len(), iface.as_ptr(), iface.len()) } < 0 {
return -1;
}
socket_id
}Important Notes:
- Receive is non-blocking - returns 0 if no data available
- Incoming datagrams are buffered (max 1000 per socket)
- Oldest datagrams are dropped if buffer is full
- All sockets are automatically closed when plugin stops
- Use
sk_udp_pending()to check if data is available before callingsk_udp_recv()
The rawSockets capability also enables TCP socket access for plugins that need persistent connections to devices:
- Marine radars with TCP control (Furuno, Garmin)
- Devices requiring handshake/login protocols
- Any marine electronics using TCP
TCP sockets support both line-buffered mode (for text protocols with \r\n terminators) and raw mode (for binary protocols).
FFI Functions Available:
| Function | Signature | Description |
|---|---|---|
sk_tcp_create |
() -> i32 |
Create TCP socket. Returns socket_id or -1 |
sk_tcp_connect |
(socket_id, addr_ptr, addr_len, port) -> i32 |
Initiate connection (non-blocking). Returns 0 or -1 |
sk_tcp_connected |
(socket_id) -> i32 |
Check connection status. Returns 1 if connected, 0 otherwise |
sk_tcp_set_line_buffering |
(socket_id, enabled) -> i32 |
Set buffering mode (1=line, 0=raw). Default: line |
sk_tcp_send |
(socket_id, data_ptr, data_len) -> i32 |
Send data. Returns bytes sent or -1 |
sk_tcp_recv_line |
(socket_id, buf_ptr, buf_max_len) -> i32 |
Receive complete line (line mode). Returns len or 0 |
sk_tcp_recv_raw |
(socket_id, buf_ptr, buf_max_len) -> i32 |
Receive raw data (raw mode). Returns len or 0 |
sk_tcp_pending |
(socket_id) -> i32 |
Get buffered item count |
sk_tcp_close |
(socket_id) -> void |
Close socket |
Rust Example:
#[link(wasm_import_module = "env")]
extern "C" {
fn sk_tcp_create() -> i32;
fn sk_tcp_connect(socket_id: i32, addr_ptr: *const u8, addr_len: usize, port: u16) -> i32;
fn sk_tcp_connected(socket_id: i32) -> i32;
fn sk_tcp_set_line_buffering(socket_id: i32, enabled: i32) -> i32;
fn sk_tcp_send(socket_id: i32, data_ptr: *const u8, data_len: usize) -> i32;
fn sk_tcp_recv_line(socket_id: i32, buf_ptr: *mut u8, buf_max_len: usize) -> i32;
fn sk_tcp_recv_raw(socket_id: i32, buf_ptr: *mut u8, buf_max_len: usize) -> i32;
fn sk_tcp_pending(socket_id: i32) -> i32;
fn sk_tcp_close(socket_id: i32);
}
// Example: Furuno radar control connection
fn connect_furuno_radar(ip: &str, port: u16) -> i32 {
// Create TCP socket
let socket_id = unsafe { sk_tcp_create() };
if socket_id < 0 {
return -1;
}
// Initiate connection (non-blocking)
if unsafe { sk_tcp_connect(socket_id, ip.as_ptr(), ip.len(), port) } < 0 {
return -1;
}
socket_id
}
fn poll_connection(socket_id: i32) {
// Check if connected
if unsafe { sk_tcp_connected(socket_id) } != 1 {
return; // Still connecting
}
// Send command with \r\n terminator
let cmd = "$S69,2,0,0,60,300,0\r\n";
unsafe { sk_tcp_send(socket_id, cmd.as_ptr(), cmd.len()) };
// Receive response line
let mut buf = [0u8; 256];
let len = unsafe { sk_tcp_recv_line(socket_id, buf.as_mut_ptr(), buf.len()) };
if len > 0 {
// Process response
}
}Important Notes:
- Connection is non-blocking - poll
sk_tcp_connected()until connected - Line-buffered mode (default) splits incoming data on
\r\nor\n - Raw mode returns data as it arrives (for binary protocols)
- Use
sk_tcp_pending()to check if data is available - All sockets are automatically closed when plugin stops
The bluetooth capability gives a plugin access to the server-managed BLE API. The server owns the Bluetooth hardware (local adapters and remote gateways), so a WASM plugin can read BLE sensors such as wind meters or battery monitors without D-Bus access or threads of its own.
A plugin works with BLE in two ways:
- GATT subscriptions: the plugin hands the server a GATT subscription descriptor (the same JSON shape the BLE API uses for
subscribeGATT) and gets back a handle. The server selects the provider, connects, subscribes to the listed characteristics and reconnects after a drop. Through the handle the plugin can write to a characteristic of the connected device and close the subscription. - Advertisements: the plugin receives every advertisement the server sees, merged across all providers.
A WASM plugin cannot wait for asynchronous work, so every BLE host function returns at once. Its outcome reaches the plugin as JSON events through the optional ble_handler export, which receives one event string per call, just as delta_handler receives deltas. Events report connection and disconnection of a subscription, characteristic notifications, failures that happen after a call returned (a device that cannot be reached, a write that fails), and advertisements. Binary payloads are hex-encoded, matching the BLE API's descriptor and advertisement formats. A subscription reports connected before its first notification. Events raised while the plugin's start function runs are delivered as soon as it returns, and none are delivered after the plugin stops.
Error codes are negative: -1 when the capability is not granted, -2 when the server has no BLE API, -3 for invalid input, -4 for an unknown handle and -5 for a write to a subscription that is not connected.
The plugin acts as a BLE consumer under its plugin ID, so its GATT claims and advertisement subscription appear in the BLE Manager. All of them are released when the plugin stops.
| Function | Signature | Purpose |
|---|---|---|
sk_ble_subscribe_gatt |
(desc_ptr, desc_len) -> handle |
Start a GATT subscription from a descriptor |
sk_ble_gatt_write |
(handle, uuid_ptr, uuid_len, data_ptr, data_len, with_response) -> i32 |
Write bytes to a characteristic of a device |
sk_ble_gatt_close |
(handle) -> i32 |
Close a GATT subscription and release the claim |
sk_ble_subscribe_advertisements |
() -> i32 |
Start receiving advertisements |
sk_ble_unsubscribe_advertisements |
() -> i32 |
Stop receiving advertisements |
Every event carries a type. Subscription events also carry the handle they belong to:
type |
Further fields |
|---|---|
connected |
handle |
disconnected |
handle |
notify |
handle, uuid (characteristic), data (hex) |
error |
handle, message |
advertisement |
advertisement (a BLEAdvertisement of the BLE API) |
AssemblyScript plugins use the wrappers and error code constants from the SDK's ble module.
WASM plugins can register PUT handlers to respond to PUT requests from clients, enabling vessel control and configuration management.
Requirements:
- Plugin must declare
"putHandlers": truein manifest - Import PUT handler functions from FFI
- Register handlers during
plugin_start() - Export handler functions with correct naming convention
Manifest Configuration:
{
"name": "my-plugin",
"wasmManifest": "plugin.wasm",
"wasmCapabilities": {
"putHandlers": true
}
}Handler Naming Convention:
Format: handle_put_{context}_{path}
- Replace all dots (
.) with underscores (_) - Convert to lowercase (recommended)
Examples:
| Context | Path | Handler Function Name |
|---|---|---|
vessels.self |
navigation.anchor.position |
handle_put_vessels_self_navigation_anchor_position |
vessels.self |
steering.autopilot.target.headingTrue |
handle_put_vessels_self_steering_autopilot_target_headingTrue |
Handler Signature:
- AssemblyScript:
(value: string): string, taking the PUT value as JSON and returning the response as JSON - Rust:
(value_ptr, value_len, response_ptr, response_max_len) -> written_len, writing the response JSON into the given buffer
Response Format:
{
"state": "COMPLETED",
"statusCode": 200,
"message": "Operation successful"
}state- Request state:COMPLETEDorPENDINGstatusCode- HTTP status code (200, 400, 403, 500, 501)message- Human-readable message (optional)
Plugins have access to isolated virtual filesystem:
use std::fs;
fn save_state() {
// Plugin sees "/" as its VFS root
fs::write("/data/state.json", state_json).unwrap();
}
fn load_state() -> String {
fs::read_to_string("/data/state.json").unwrap_or_default()
}VFS Structure:
/ (VFS root)
├── data/ # Persistent storage
├── config/ # Plugin-managed config
└── tmp/ # Temporary files
Emit delta messages to update Signal K data:
fn emit_position_delta() {
let delta = r#"{
"context": "vessels.self",
"updates": [{
"source": {
"label": "example-wasm",
"type": "plugin"
},
"timestamp": "2025-12-01T10:00:00.000Z",
"values": [{
"path": "navigation.position",
"value": {
"latitude": 60.1,
"longitude": 24.9
}
}]
}]
}"#;
handle_message(&delta);
}