Script Parameters Guide

Overview

Script parameters are a lightweight way to pass per-device configuration into a script without rebuilding or re-uploading the script itself. They let the same compiled script behave differently on different devices, depending only on what was typed into the configuration.

When a script is attached to a configuration, right below free-form string field located. The user fills it with their own parameters using INI-style formatting (key = value). After the configuration is uploaded to the device, the script can read that string and pull individual values out of it using the helper functions in <script_parameters>.

How it works

The end-to-end flow has four steps:

Step	Where it happens	What happens
1	Configuration tool	User attaches the script to a configuration and types the parameter string (INI-style text) into the string field.
2	Device	Configuration is uploaded. The parameter string is stored in the device settings.
3	Script (runtime)	User first must add `#include <script_parameters>`, then in Script call script_params_read() to copy that parameter string into a local buffer.
4	Script (runtime)	(Optional) Script calls script_params_ini_val_get() for each key it needs and converts the returned string into the proper type.

The parameters string format

The string field uses a small subset of INI syntax:

Each entry is on its own line.
Format is key = value. Spaces and tabs around the = are tolerated.
Values are read as raw text until the end of the line. There is no quoting — leading whitespace after = is trimmed, everything else is kept.
Keys are matched on word boundaries, so "id" will not accidentally match "can_id".
Case sensitivity is chosen per call (via the case_sensitive argument).

Example parameter string

This is what the user might type into the string field next to the attached script:

; Example INI configuration file
; This is a comment

[General]
publish_sensor_id = 16300
bool_sensor = true
name = Beacon_name
temperature_threshold = 22.5

[RS232]
rs232_baud_rate = 9600

[CAN BUS]
can_id = 1
can_baud_rate = 500000

The helper functions

In order to use helper functions users must add #include <script_parameters> at the start of script.

Two functions in <script_parameters> cover the typical use case:

script_params_read()

Reads the raw parameter string assigned to the running script and stores it in a local buffer. Call it once at the beginning of main().

Returns SCRIPT_OPERATION_SUCCESS on success, -1 if the script ID or settings could not be read.

script_params_ini_val_get()

Searches the buffer (the string returned by script_params_read()) for a given key and copies its value into a small output array.

Returns SCRIPT_OPERATION_SUCCESS on success, -1 if the key was not found or no = was present after it.

Values are returned as strings

This is the most common source of bugs, so it is worth stating clearly: script_params_ini_val_get() always returns the value as a string. Even if the user typed sample_rate = 100 the script gets the three characters "100", not the integer 100.

If the script needs a numeric value, it must convert the returned string itself:

Use strval() to convert to an integer ("100" -> 100).
Use strfloat() to convert to a floating-point number ("1.25" -> 1.25).
Hex literals like 0x18FF50E5 are also returned as strings.
Pure-text values (names, identifiers, flags like on/off) can be used directly without conversion.

Tip

Reuse a single small str_value[] buffer for every script_params_ini_val_get() call and convert immediately to the target type. There is no need to keep the string form around.

if (script_params_ini_val_get(ini_file, "sample_rate", true, str_value) == SCRIPT_OPERATION_SUCCESS)
{
    new rate = strval(str_value);   // "100"   -> 100
}

if (script_params_ini_val_get(ini_file, "gain", true, str_value) == SCRIPT_OPERATION_SUCCESS)
{
    new Float:gain = strfloat(str_value);  // "1.25" -> 1.25
}

Putting it together

Full example using the INI string from the Example parameter string section above:

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <debug>
#include <script_parameters>

#define INI_FILE_SIZE   500
#define RS232_SPEED     115200
#define WORD_LENGTH     WORDLENGTH_8
#define STOP_BITS       STOPBITS_1
#define PARITY          PARITY_NONE

new ini_file[INI_FILE_SIZE];

main()
{
    new ret_val;
    new str_value[32];
    new can_id;
    new Float:temperature_threshold;

    Init(RS232, RS232_SPEED, WORD_LENGTH, STOP_BITS, PARITY);
    debug_init(RS232);
    
    // 1. Read the whole script parameters string into ini_file
    ret_val = script_params_read(ini_file);
    if (ret_val != 1)
    {
        debug_print("Failed to read script parameters\r\n");
        return;
    }
    
    // 2. Fetch the value for "can_id" and convert string -> integer
    if (script_params_ini_val_get(ini_file, "can_id", true, str_value) == SCRIPT_OPERATION_SUCCESS)
    {
        can_id = strval(str_value, 0);
        debug_print("can_id = %i\r\n", can_id);
    }
    
    // 3. Fetch a floating-point value and convert string -> float
    if (script_params_ini_val_get(ini_file, "temperature_threshold", true, str_value) == SCRIPT_OPERATION_SUCCESS)
    {
        temperature_threshold = strfloat(str_value);
        debug_print("temperature_threshold = %f\r\n", temperature_threshold);
    }

    for(;;)
    { 
        Delay(1000); 
    }
}

Possible pitfalls

Forgetting that script_params_ini_val_get() returns SCRIPT_OPERATION_SUCCESS or -1, not 0. Compare against SCRIPT_OPERATION_SUCCESS (or != SCRIPT_OPERATION_SUCCESS).
Sizing the ini_file[] buffer too small. If the user's parameter string is longer than the buffer, it will be truncated and later ini_val_get calls may fail for keys near the end.
Forgetting to convert the string. To compare a numeric parameter, run it through strval() or strfloat() first — comparing the raw string buffer with an integer or float will not give the expected result.
Putting two keys on the same line. Each key = value must be on its own line — the value extends to the next newline.
Calling script_params_read() before script_id_get() is ready (e.g. before the runtime has initialized). If it returns -1, retry or initialize peripherals first.