RedVox API 1000

This repository contains the RedVox API 1000 protocol definition as well as several wrappers generated by the protobuf compiler.

Protocol buffers (often shortened to just "protobuf") are a type-safe system for serializing and deserializing structured data between different programming languages and systems.

Specification

The RedVox API 1000 specification can be found at src/redvox_api_m/redvox_api_m.proto.

It's fairly small, fairly readable, and well documented. This is the best and first place to refer for documentation for API 1000.

Protobuf generated wrappers

Wrappers generated by protobuf for working with the raw RedVox API 1000 protocol are provided below as well as API documentation for those wrappers:

Changes from API 900

RedVox API 900 is the previous generation of the RedVox data protocol.

Major changes for API M that are not in API 900 include:

Enhanced station metadata
A copy of the station's app's settings
Enhanced station metrics (network type, network strength, temperature, cell service state, battery remaining, battery current, available RAM, available disk, CPU utilization, power state, and WiFi wake lock)
Type safe enumerations for representing finite values
Enhanced timing
- More robust time synchronization exchange algorithm
- Include end timestamps that correspond to the last audio sample in a packet
- Store best latecy and offset metrics
Enhanced location
- Include machine AND GPS timestamps
- Add bearing samples to latitude, longitude, altitude, and speed
- Add horizontal, speed, and bearing accuracy to vertical accuracy
- Store most recent best location and best overall location
- Manage location permissions
- Provide location providers (i.e. Network, GPS, etc)
Sensors are expanded and specialized as their own Message types
- Xyz (3-channel sensors) (accelerometer, gravity, gyroscope, linear acceleration, magnetometer, orientation, rotation vector, velocity)
- Single (1-channel sensors) (ambient temperature, light, pressure, proximity, relative humidity)
- Audio (Audio sensor)
- CompressedAudio (Compressed audio sensor)
- Image (Image and video sensor)
- Location (Location sensor)
All physical units are stored alongside the values so users never need to guess which units a value are in
EventStreams (provide streams of on-app detected and derived sensor events (i.e. station movement))
Per Message metadata (untyped metadata is available in each message definition for future expansion)
Enhanced security
- Various security tokens are no longer included in the packet
- paseto tokens are used to authenticate and authorize packets being receieved by the acquisition server
- Tokens now enforce a strict validation window to mitigate token copy-cat attacks
Improved modularization
- Metadata is now encapsulated with other related metadata
Improved compression
- Migrate from LZ4 block protocol to the LZ4 frame protocol
Audio data type
- Audio data is now stored as PCM floating point
- Integer scaling is provided in the audio metadata
Audio sampling rates (80 Hz, 800 Hz, 8 kHz, 16 kHz, 48 kHz)
Audio window lengths
- API M supports variable packet lengths for each sampling rate
- The window sizes utilize a power of 2 number of samples and are between 1 second and 1 minute
CompressedAudio
- API M now supports compressed audio using the FLAC compression protocol
Improved client/server communications
- The acquisition response protocol has been updated to deal with duplicate packets and bad network connections

Detailed Documentation Topics

Changelog