Skip to content

Xylolabs Knowledge Base

Indexed reference for the Xylolabs IoT audio and sensor monitoring platform. XAP and XMBP are patent-pending proprietary technologies of Xylolabs Inc.

Core Protocols (Patent Pending)

These two protocols form the foundation of the Xylolabs data pipeline. All device firmware, SDK code, and server ingest logic is built around them.

XAP — Xylolabs Audio Protocol

XAP is Xylolabs' proprietary MDCT-based spectral audio codec for real-time multi-channel audio compression on resource-constrained IoT and industrial monitoring hardware. Codec ID 0x03 in XMBP.

Property Value
Transform MDCT
Sample rates 8, 16, 24, 32, 48, 96 kHz
Channels 1–4
Frame durations 7.5 ms, 10 ms
Compression ratio 8:1–10:1
Bitrate range 16–320 kbps per channel
CPU requirement ~10 MIPS/channel (with DSP)
RAM per channel ~8 KB encoder state

XMBP — Xylolabs Metadata Binary Protocol

XMBP is the compact binary framing protocol for IoT sensor and motor telemetry. It is the on-wire format between all Xylolabs-SDK-equipped devices and the ingest server. Magic bytes: 0x58 0x4D 0x42 0x50 ("XMBP").

Property Value
Byte order Big-endian (network order)
Timestamps u64 microseconds
Min batch size 10 bytes (no device ID, no streams)
Allocation Zero — writes directly into caller-supplied buffer
Storage format XMCH (on-server)
  • XMBP Specification — Wire format, batch envelope, stream block layout, sample layout, value type registry, audio codec identifiers, encoding/decoding API, feature flags, transport, XMCH storage format, wire format examples
  • XMBP Specification (한국어)

Codec Analysis & Performance

Analysis and benchmark data for XAP and all evaluated competing codecs across MCU targets.

Architecture Diagrams

Visual references located in diagrams/:

Diagram File
System architecture overview diagrams/architecture.svg
Ingest pipeline diagrams/ingest-pipeline.svg
Codec comparison chart diagrams/codec-comparison.svg
SDK platform map diagrams/sdk-platforms.svg
Feasibility option A diagrams/feasibility-option-a.svg
Feasibility option B diagrams/feasibility-option-b.svg
Feasibility option C diagrams/feasibility-option-c.svg
Time sync diagram diagrams/feasibility-time-sync.svg
Window alignment diagram diagrams/feasibility-window-align.svg

Platform Guides

Per-MCU integration guides covering hardware setup, pin assignments, codec capability, and SDK wiring.

RP2350 / Pico 2 W (Primary Target)

The primary reference target. Dual Cortex-M33 @ 150 MHz, 520 KB SRAM, PIO-based I2S, CYW43 WiFi/BT, ARMv8-M DSP extensions. Requires external I2S ADC for 96 kHz/24-bit audio.

ESP32-S3 / ESP32-C3

Native WiFi — no external LTE modem required. ESP32-S3 supports 4ch XAP @ 96 kHz via 128-bit Xtensa SIMD. ESP32-C3 (RISC-V) is a sensor-only node.

STM32 (F103, F411, WB55, WBA55)

Cortex-M3/M4F/M33 targets. F411, WB55, and WBA55 support XAP (FPU + DSP). WB55 adds BLE with 4ch ADC at 48 kHz; WBA55 at 96 kHz. F103 is sensor-only (no FPU).

nRF52840 / nRF9160

Nordic Cortex-M4F / Cortex-M33 targets. nRF52840 transports via BLE 5.0; nRF9160 via LTE-M / NB-IoT.

RP2040 / Pico (ADPCM-only)

Dual Cortex-M0+ @ 133 MHz, 264 KB SRAM. No FPU or DSP — XAP is not feasible. ADPCM only. Cost-effective sensor node.

Hardware

Reference hardware documentation for the Xylolabs RP2350 full sensor node.

  • Hardware BOM — Complete bill of materials: MCU (RP2350), audio ADC (PCM1860QDBTRQ1), microphones (WM-61A), environment sensor (SEN0385/CHT832X), accelerometer (ADXL345), LTE modem (BG770A), passives, connectors, purchase links
  • Hardware BOM (한국어)

Firmware & OTA

  • Firmware releases are uploaded to S3 and tracked in the firmware_releases table
  • Deployments target specific devices via the firmware_deployments table with status tracking (pending → downloading → verified → applied)
  • Devices poll /api/v1/ota/check with their hardware_target to discover updates
  • Progress is reported back via /api/v1/ota/deployments/{id}/progress
  • Admin manages releases and deployments via the Firmware page in the dashboard

Server Features

XAP Server-Side Decoder

The xylolabs-transcode crate includes a full XAP decoder (xap_decode.rs) that reconstructs PCM from XAP-encoded audio. The transcode pipeline automatically detects .xap uploads and decodes them to WAV before FFmpeg transcoding.

  • Inverse MDCT transform: x[n] = (2/N) * Σ X[k] * cos(π/N * (n+0.5+N/4) * (k+0.5))
  • Adaptive dequantization: coeff = quantized_i8 * step_size
  • Supports all XAP sample rates (8–96 kHz), 1–4 channels
  • Sample rate inferred from frame header frame_samples field

Transcode Queue & Stale Job Reaper

Transcoding uses a Postgres-backed job queue with FOR UPDATE SKIP LOCKED for atomic claiming. The worker includes:

  • Bounded concurrency via Semaphore (configurable, 1–32)
  • Event-driven via pg_notify('transcode_queue') with 10s polling fallback
  • Stale job reaper: on startup and every 60s, requeues jobs stuck in 'running' past TRANSCODE_STALE_TIMEOUT_SECS (default 7200 = 2 hours)
  • Retry with backoff: failed jobs auto-requeue if under max_attempts

Ingest Session Modes

Sessions operate in one of two modes, configured at creation time:

Mode Timeout Use Case
continuous (default) session_timeout_secs (5 min) Nonstop streaming (vibration monitors, audio)
sampling max(sampling_timeout_secs, interval×3) (1h+) Periodic measurement with idle gaps (battery sensors)

Sampling-mode sessions carry additional fields: - sampling_interval_secs: expected seconds between measurement starts (e.g., 300 = 5 min) - sampling_duration_secs: expected seconds per measurement burst (e.g., 10)

The IngestManager uses per-session timeout instead of a global value. This prevents session explosion for devices that sleep between measurement cycles. The frontend detects gaps in time-series data and breaks chart lines at measurement boundaries.

Metadata Stream Visualization

The admin dashboard (admin.api.xylolabs.com) includes a metadata visualization frontend:

  • Uploads list (/metadata): paginated table with device filter, status filter, mode filter, stream counts, sample totals, data sizes
  • Session detail (/metadata/:id): per-stream time-series charts (Recharts LineChart), time range selector, sampling info panel, gap-aware rendering for sampling-mode sessions, non-numeric table fallback
  • Audio waveform (/uploads/:id): wavesurfer.js interactive waveform player with play/pause and time scrubbing
  • Device fleet (/): dashboard with device health status bar, active sessions panel, recent uploads panel

API Reference

REST API documentation for the Xylolabs server.

  • API Documentation (English) — Full REST API reference: authentication, facilities, users, API keys, devices, audio upload, audio streaming, transcode jobs, tags, metadata ingest, metadata query, system configuration, dashboard stats, health, XMBP protocol reference, RBAC, error responses, data models, pagination, example workflows
  • API Documentation (한국어)

SDK — Rust Crates

The Rust SDK is the recommended path for all new firmware development. All crates are no_std-compatible.

Core SDK

HAL Crates (Platform Implementations)

Crate Target Transport Codec
xylolabs-hal-rp RP2350 (Pico 2) LTE-M1 modem via UART XAP
xylolabs-hal-esp ESP32-S3, ESP32-C3 Native WiFi (esp-wifi) XAP / ADPCM
xylolabs-hal-stm32 STM32F103, F411, WB55, WBA55 LTE-M1 modem via UART / BLE GATT XAP / ADPCM
xylolabs-hal-nrf nRF52840, nRF9160 BLE GATT / LTE-M XAP / ADPCM

Korean versions: hal-rp · hal-esp · hal-stm32 · hal-nrf

Code Examples

Legacy C reference examples. For new development, use the Rust SDK.

Platform Example Description
RP2350 docs/examples/pico/ C examples: continuous sensor streaming, periodic sampling, audio upload via I2S + chunked HTTP
RP2350 Full Hardware docs/examples/rp2350-full-hardware/ Field-deployable node: PCM1860 + WM-61A + CHT832X + ADXL345 + BSS84 + BG770A wired to RP2350
ESP32 docs/examples/esp32/ C examples: ESP32-S3 full audio + sensors (XAP, WiFi), ESP32-C3 lightweight sensor-only (XMBP over WiFi)
STM32 docs/examples/stm32/ C examples: F411 audio + sensors (XAP, LTE-M1), F103 sensor-only (ADPCM, LTE-M1), WB55 BLE sensor node
nRF docs/examples/nrf/ C example: nRF52840 BLE sensor beacon with XMBP, ultra-low-power sleep

Korean versions: pico · rp2350-full-hardware · esp32 · stm32 · nrf

Quick Reference

Codec Selection by Platform

Platform XAP ADPCM Notes
RP2350 (Pico 2) Yes — 4ch @ 96 kHz Yes Primary target
ESP32-S3 Yes — 4ch @ 96 kHz Yes Native WiFi
ESP32-C3 No (no FPU) Yes Sensor node only
STM32F411 Yes — 4ch @ 48 kHz Yes
STM32WB55 Yes — 2ch @ 48 kHz Yes BLE offload
STM32F103 No (no FPU) Optional Sensor node only
nRF52840 Yes — 2ch @ 48 kHz Yes Via BLE gateway
nRF9160 No Yes Sensor node only
RP2040 (Pico) No (no FPU) Yes Sensor node only

XMBP Value Type Registry (quick lookup)

See XMBP Specification §5 for the full registry. Audio codec identifiers (including XAP 0x03) are defined in §6.

I16 and I8 Types — Compact Sensor Encoding

XMBP supports two compact integer types for bandwidth-sensitive sensor streams:

Type Wire Tag Value Size Total Sample Size Bandwidth vs F32
i16 0x0B 2 bytes 10 bytes −17% vs F32 (12 bytes)
i8 0x0C 1 byte 9 bytes −25% vs F32 (12 bytes)

Use cases:

  • ADXL345 accelerometer: Raw ADC output is 10–13 bits, fitting naturally in i16. Using i16 instead of f32 saves 17% bandwidth per axis per sample on Cat-M1 links.
  • CHT832X / SHT31 temperature and humidity: 14-bit temperature and 11-bit humidity readings can be stored as raw i16 counts (e.g., hundredths of a degree), avoiding floating-point conversion overhead on no-FPU targets.
  • Any sensor producing small integer ADC counts that would lose no precision in 8–16 bit representation.

SDK methods: meta_feed_i16(stream_index, value: i16) and meta_feed_i8(stream_index, value: i8). These mark the stream type automatically; no separate type declaration is needed per sample. The SDK flushes the stream using write_stream_i16_bulk / write_stream_i8_bulk for efficient batch encoding.

Revision: 2026-03-27