Memory Configuration

The Plexus C SDK uses compile-time flags to control buffer sizes and feature toggles. You can reduce RAM usage from the default ~17 KB down to ~1.5 KB by disabling features you do not need.

Configuration Options

Override any of these defaults by defining them before including plexus.h or via compiler flags (e.g., -DPLEXUS_MAX_METRICS=8).

Buffer Sizes

Tag Settings

Network Settings

Auto-Flush Settings

Feature Toggles

RAM Usage Breakdown

The client struct (plexus_client_t) is the only RAM allocation. Its size depends on your configuration:

The size of plexus_metric_t is 472 bytes with all features enabled (strings, bools, tags). Disabling string values removes 128 bytes per metric and disabling tags removes 257 bytes per metric — this is the main lever for reducing RAM. Use plexus_client_size() at runtime or PLEXUS_CLIENT_STATIC_SIZE at compile time to get the exact size for your configuration.

Default vs Minimal

Default Configuration

All features enabled, 32 metrics per flush:

// No flags needed — these are the defaults
plexus_client_t* px = plexus_init("plx_xxxxx", "device-001");
printf("Client size: %u bytes\n", (unsigned)plexus_client_size());
// => ~17704 bytes

Minimal Configuration

Numbers only, 8 metrics per flush, small buffers:

-DPLEXUS_MAX_METRICS=8
-DPLEXUS_ENABLE_TAGS=0
-DPLEXUS_ENABLE_STRING_VALUES=0
-DPLEXUS_ENABLE_BOOL_VALUES=0
-DPLEXUS_JSON_BUFFER_SIZE=512
-DPLEXUS_MAX_ENDPOINT_LEN=128
-DPLEXUS_MAX_API_KEY_LEN=64

This reduces plexus_client_size() to approximately 1.5 KB.

In CMake:

target_compile_definitions(your_target PRIVATE
    PLEXUS_MAX_METRICS=8
    PLEXUS_ENABLE_TAGS=0
    PLEXUS_ENABLE_STRING_VALUES=0
    PLEXUS_ENABLE_BOOL_VALUES=0
    PLEXUS_JSON_BUFFER_SIZE=512
    PLEXUS_MAX_ENDPOINT_LEN=128
    PLEXUS_MAX_API_KEY_LEN=64
)

In Arduino/PlatformIO (platformio.ini):

build_flags =
    -DPLEXUS_MAX_METRICS=8
    -DPLEXUS_ENABLE_TAGS=0
    -DPLEXUS_ENABLE_STRING_VALUES=0
    -DPLEXUS_ENABLE_BOOL_VALUES=0
    -DPLEXUS_JSON_BUFFER_SIZE=512
    -DPLEXUS_MAX_ENDPOINT_LEN=128
    -DPLEXUS_MAX_API_KEY_LEN=64

Persistent Buffering

Enable flash-backed storage so unsent data survives power cycles and reboots:

-DPLEXUS_ENABLE_PERSISTENT_BUFFER=1

When a flush fails, the SDK writes queued metrics to persistent storage (NVS on ESP32). On the next successful connection, stored data is sent first.

The persistent buffer HAL must be implemented for your platform. The ESP32 HAL uses NVS (nvs_flash). For STM32, you would implement plexus_hal_storage_write/read/clear using your flash storage driver.

Thread Safety

Enable mutex-protected client access for multi-threaded environments:

-DPLEXUS_ENABLE_THREAD_SAFE=1

When enabled, all public API calls acquire a mutex before accessing client state. The mutex HAL must be implemented for your platform:

Without PLEXUS_ENABLE_THREAD_SAFE, the SDK is not thread-safe. Confine all calls for a given client to a single thread. Multiple clients in separate threads is always safe.

Blocking Behavior

plexus_flush() can block during retries. Here is the worst-case timing:

To avoid blocking your main loop, reduce PLEXUS_MAX_RETRIES or use FreeRTOS with a dedicated telemetry task.

Next Steps

• API Reference -- Full function and macro reference
• ESP32 Guide -- Complete ESP-IDF walkthrough
• STM32 Guide -- STM32 with FreeRTOS and LwIP