Configuration

Read and update your device's configuration stored on RelayX.

Overview

The configuration module lets your device fetch its current configuration and push updates. This is useful for settings that should persist across device restarts — things like sampling intervals, thresholds, feature flags, or calibration values.

API

get()

Fetch the device's current configuration from RelayX.

JavaScript

await device.config.get()

Returns the device's configuration object, or {} if no configuration has been set

Throws TimeoutError if the server doesn't respond in time

Throws NotConnectedError if the device is not connected

Python

await device.config.get()

Returns the device's configuration object, or {} if no configuration has been set

Throws TimeoutError if the server doesn't respond in time

Throws NotConnectedError if the device is not connected

C++

device->config_mgr.get(callback) → relay_err_t

Parameter	Type	Description
callback	relay_config_get_cb_t	void (*)(relay_err_t err, const char* json_data, size_t len)

Non-blocking — the callback fires during a future process() call when the server responds. Returns RELAY_ERR_NOT_CONNECTED immediately if offline. The callback receives RELAY_ERR_TIMEOUT if the server doesn't respond.

set()

Replace the device's configuration on RelayX with a new object.

JavaScript

await device.config.set(data)

Parameter	Type	Description
data	object	The configuration object to store

Returns true if the configuration was updated successfully, false otherwise

Throws TimeoutError if the server doesn't respond in time

Throws NotConnectedError if the device is not connected

Python

await device.config.set(data)

Parameter	Type	Description
data	object	The configuration object to store

Returns true if the configuration was updated successfully, false otherwise

Throws TimeoutError if the server doesn't respond in time

Throws NotConnectedError if the device is not connected

C++

device->config_mgr.set(json_data, callback) → relay_err_t

Parameter	Type	Description
json_data	const char*	JSON string of the configuration to store
callback	relay_config_set_cb_t	void (*)(relay_err_t err)

Non-blocking — the callback fires during a future process() call with RELAY_OK on success or RELAY_ERR_TIMEOUT. Returns RELAY_ERR_NOT_CONNECTED immediately if offline.

Get Configuration

JavaScript

const config = await device.config.get();
console.log("Sampling interval:", config.samplingInterval);
console.log("Threshold:", config.alertThreshold);

Python

config = await device.config.get()
print("Sampling interval:", config["samplingInterval"])
print("Threshold:", config["alertThreshold"])

C++

device->config_mgr.get([](relay_err_t err, const char* json_data, size_t len) {
    if (err != RELAY_OK) {
        ESP_LOGE("app", "Failed to get config");
        return;
    }

    cJSON* config = cJSON_Parse(json_data);
    int interval = cJSON_GetObjectItem(config, "samplingInterval")->valueint;
    int threshold = cJSON_GetObjectItem(config, "alertThreshold")->valueint;
    ESP_LOGI("app", "Sampling interval: %d, Threshold: %d", interval, threshold);
    cJSON_Delete(config);
});

Update Configuration

JavaScript

const updated = await device.config.set({
  samplingInterval: 5000,
  alertThreshold: 80,
  featureFlags: {
    deepSleep: true,
    logging: false,
  },
});

console.log(updated ? "Config saved" : "Update failed");

Python

updated = await device.config.set({
    "samplingInterval": 5000,
    "alertThreshold": 80,
    "featureFlags": {
        "deepSleep": True,
        "logging": False,
    },
})

print("Config saved" if updated else "Update failed")

C++

cJSON* config = cJSON_CreateObject();
cJSON_AddNumberToObject(config, "samplingInterval", 5000);
cJSON_AddNumberToObject(config, "alertThreshold", 80);

cJSON* flags = cJSON_CreateObject();
cJSON_AddBoolToObject(flags, "deepSleep", true);
cJSON_AddBoolToObject(flags, "logging", false);
cJSON_AddItemToObject(config, "featureFlags", flags);

char* json = cJSON_PrintUnformatted(config);
device->config_mgr.set(json, [](relay_err_t err) {
    ESP_LOGI("app", "%s", err == RELAY_OK ? "Config saved" : "Update failed");
});

free(json);
cJSON_Delete(config);

info

set() replaces the entire configuration object. To update a single field, fetch the current config with get(), modify it, and pass the full object back to set().

Read-Modify-Write Pattern

JavaScript

// fetch current config
const config = await device.config.get();

// modify a single field
config.alertThreshold = 90;

// save it back
await device.config.set(config);

Python

# fetch current config
config = await device.config.get()

# modify a single field
config["alertThreshold"] = 90

# save it back
await device.config.set(config)

C++

// fetch current config, modify, and save back
device->config_mgr.get([](relay_err_t err, const char* json_data, size_t len) {
    if (err != RELAY_OK) return;

    cJSON* config = cJSON_Parse(json_data);
    cJSON_ReplaceItemInObject(config, "alertThreshold", cJSON_CreateNumber(90));

    char* updated = cJSON_PrintUnformatted(config);
    device->config_mgr.set(updated, [](relay_err_t err) {
        ESP_LOGI("app", "%s", err == RELAY_OK ? "Saved" : "Failed");
    });

    free(updated);
    cJSON_Delete(config);
});

Error Handling

JavaScript

Both get() and set() require an active connection and will throw if the device is offline or the server doesn't respond.

try {
  const config = await device.config.get();
} catch (err) {
  if (err.name === "NotConnectedError") {
    console.error("Device is offline");
  } else if (err.name === "TimeoutError") {
    console.error("Server did not respond");
  }
}

Python

Both get() and set() require an active connection and will throw if the device is offline or the server doesn't respond.

try:
    config = await device.config.get()
except NotConnectedError:
    print("Device is offline")
except TimeoutError:
    print("Server did not respond")

C++

get() and set() return RELAY_ERR_NOT_CONNECTED immediately if offline. Timeout errors arrive in the callback.

relay_err_t err = device->config_mgr.get([](relay_err_t err, const char* json_data, size_t len) {
    if (err == RELAY_ERR_TIMEOUT) {
        ESP_LOGE("app", "Server did not respond");
        return;
    }
    // use json_data
});

if (err == RELAY_ERR_NOT_CONNECTED) {
    ESP_LOGE("app", "Device is offline");
}