Ruten SDK Reference
Everything you need to integrate the closed-loop middleware into your device firmware: quickstart guide, full API reference, configuration schema, and device adapter examples.
Quickstart
The Ruten SDK is delivered as a C static library with a single header include. Initialize the acquisition context, configure the safety profile, and start the decode loop in under 50 lines of integration code.
/* Ruten SDK - minimal integration example */
#include "ruten/rtn_sdk.h"
int main(void) {
rtn_config_t cfg = rtn_config_load("device_config.json");
rtn_context_t ctx = rtn_init(&cfg);
rtn_acquire_start(&ctx);
while (rtn_acquire_ready(&ctx)) {
rtn_frame_t frame = rtn_acquire_read(&ctx);
rtn_intent_t intent = rtn_decode(&ctx, &frame);
if (rtn_validate(&ctx, &intent) == RTN_SAFE) {
rtn_stim_dispatch(&ctx, &intent);
}
}
return 0;
}Installation
The SDK is provided as a compressed archive containing the static library, header files, and a reference configuration file. Add the library path and include directory to your build system.
target_link_libraries(your_firmware PRIVATE ruten_sdk)
target_include_directories(your_firmware PRIVATE ruten/include)Configuration
The SDK is configured via a JSON configuration file loaded at initialization. The config file specifies hardware profile, decode parameters, and safety limits. The same binary can serve different device variants by loading different config files.
{
"hardware_profile": "ecog_32ch_spi",
"decode": {
"threshold_rms_mult": 4.5,
"update_rate_hz": 500,
"refractory_us": 1000
},
"safety": {
"max_charge_density_nC_ph": 30,
"max_pulse_width_us": 300,
"max_freq_hz": 200
}
}Acquisition API
The acquisition API provides hardware-agnostic access to electrode data streams. All functions are non-blocking; buffer management is handled internally.
| Function | Description | Returns |
|---|---|---|
rtn_acquire_start(ctx) | Begin continuous acquisition from configured electrode hardware | rtn_status_t |
rtn_acquire_ready(ctx) | Returns true if a new frame is available in the acquisition buffer | bool |
rtn_acquire_read(ctx) | Dequeue the next frame from the acquisition buffer | rtn_frame_t |
rtn_acquire_stop(ctx) | Stop acquisition and flush the buffer | rtn_status_t |
Decode API
The decode API accepts acquisition frames and returns intent vectors. The decode pipeline (artifact rejection, threshold detection, feature extraction) runs synchronously within rtn_decode().
| Function | Description | Returns |
|---|---|---|
rtn_decode(ctx, frame) | Run the full decode pipeline on an acquisition frame | rtn_intent_t |
rtn_decode_latency_us(ctx) | Return the most recent decode cycle latency in microseconds | uint32_t |
Safety API
Every stimulation command must pass through the safety validator before dispatch. The validator checks the command against the limits in the loaded safety configuration.
| Function | Description | Returns |
|---|---|---|
rtn_validate(ctx, intent) | Validate an intent vector against configured safety limits | RTN_SAFE | RTN_WARN | RTN_BLOCK | RTN_FAULT |
rtn_safe_state(ctx) | Force immediate safe-state: cease all stimulation | void |
rtn_fault_get(ctx) | Return the most recent fault code and channel | rtn_fault_t |
Stimulation API
The stimulation dispatch API sends validated commands to the stimulator driver. Dispatch is timing-precise to within the configured scheduling resolution.
| Function | Description | Returns |
|---|---|---|
rtn_stim_dispatch(ctx, intent) | Dispatch a validated intent vector to the stimulator driver | rtn_status_t |
rtn_stim_set_params(ctx, params) | Override stimulation parameters from the protocol layer | rtn_status_t |
rtn_stim_inhibit_channel(ctx, ch) | Inhibit a specific stimulation channel | void |
Hardware Setup Guide
The Ruten SDK ships with driver modules for a range of electrode and stimulator hardware. Select the appropriate hardware profile in the configuration file. If your hardware is not in the supported list, the HAL driver interface allows adding device-specific drivers without modifying the SDK core.
- Intan Technologies RHS2000 series (SPI, 32-128 channels)
- Blackrock Microsystems Cereplex Direct (USB, up to 256 channels)
- Open Ephys Acquisition Board compatible interfaces
- Custom SPI/I2C amplifier via HAL driver template
Protocol Configuration
Therapy protocol parameters (stimulation frequency, pulse width, current amplitude mapping) are defined in the protocol config section of the device configuration file. Parameters can be updated at runtime via rtn_stim_set_params() without restarting acquisition.
Safety Configuration
Safety limits are device-specific and must be set by the device manufacturer to reflect the intended tissue contact area, electrode material, and clinical protocol. The SDK enforces whatever limits you specify; it does not supply default safety limits that may not apply to your device geometry.