rcbench
Servo and ESC test bench: panel, IOmcu and shared C
Loading...
Searching...
No Matches
settings.h File Reference

Device settings: a typed schema, a value per entry, and a persistence seam. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  setting_def_t
 A setting's row of the schema: its key, unit, category, type, range, step, default and options. Its label and help line are ui_text.def's (settings_label(), settings_help()). More...
struct  settings_store_t

Macros

#define SET_CAT_SETUP_COUNT   SET_CAT_ESC
#define SET_INA_PARTS   4
 The INA3221 parts SETUP > SENSORS sets up: four, at 0x40 to 0x43, three channels each, and the rows a channel has: WATCHES, SHUNT and LIMIT (settings_sensors.h).
#define SET_INA_CHANNELS   12
#define SET_INA_CH_ROWS   3
#define SETTINGS_TEXT_MAX   24

Typedefs

typedef void(*) settings_observer_fn(setting_id_t id)
typedef void(*) settings_text_observer_fn(setting_text_id_t id)
typedef bool(*) settings_hold_fn(setting_id_t id)
typedef bool(*) settings_armed_fn(void)
 Who says whether the bench is ARMED now.

Enumerations

enum  setting_cat_t {
  SET_CAT_APP = 0 , SET_CAT_IFACE , SET_CAT_CARD , SET_CAT_SENSORS ,
  SET_CAT_ESC , SET_CAT_SUPPLY , SET_CAT_SERVO , SET_CAT_STICK ,
  SET_CAT_UPDATE , SET_CAT_COUNT
}
enum  setting_type_t { SET_TYPE_INT = 0 , SET_TYPE_FLOAT , SET_TYPE_BOOL , SET_TYPE_ENUM }
enum  setting_id_t {
  SET_PACK_CELLS = 0 , SET_PACK_MAH , SET_PACK_MOHM , SET_MOTOR_POLES ,
  SET_MOTOR_KV , SET_OUT_MIN_US , SET_OUT_MAX_US , SET_OUT_RAMP ,
  SET_THEME , SET_BRIGHTNESS , SET_CONTRAST , SET_SCREEN_ROT ,
  SET_LANGUAGE , SET_UNITS , SET_TIME_ZONE , SET_DIM_AFTER ,
  SET_PLOT_PAN , SET_KNOB_EN , SET_KNOB_SCALE , SET_INA228_EN ,
  SET_INA228_ADDR , SET_INA228_UOHM , SET_INA228_MAX_A , SET_INA3221_EN ,
  SET_INA3221_ADDR , SET_INA3221_MOHM , SET_INA3221_CH , SET_SENSE_SDA ,
  SET_SENSE_SCL , SET_ENC_EN , SET_ENC_CENTRE , SET_TONE_EN ,
  SET_TONE_PIN , SET_TONE_F_MIN , SET_TONE_F_MAX , SET_TONE_SPLIT ,
  SET_TONE_GAP , SET_TONE_PERIODS , SET_VIBE_EN , SET_OPTICAL_EN ,
  SET_OPTICAL_PIN , SET_PDMINI_EN , SET_PDMINI_TX , SET_PDMINI_RX ,
  SET_PDMINI_BAUD , SET_HITEC_RX , SET_INA_FIT_0 , SET_INA_FIT_1 ,
  SET_INA_FIT_2 , SET_INA_FIT_3 , SET_INA_W_01 , SET_INA_SH_01 ,
  SET_INA_LIM_01 , SET_INA_W_02 , SET_INA_SH_02 , SET_INA_LIM_02 ,
  SET_INA_W_03 , SET_INA_SH_03 , SET_INA_LIM_03 , SET_INA_W_11 ,
  SET_INA_SH_11 , SET_INA_LIM_11 , SET_INA_W_12 , SET_INA_SH_12 ,
  SET_INA_LIM_12 , SET_INA_W_13 , SET_INA_SH_13 , SET_INA_LIM_13 ,
  SET_INA_W_21 , SET_INA_SH_21 , SET_INA_LIM_21 , SET_INA_W_22 ,
  SET_INA_SH_22 , SET_INA_LIM_22 , SET_INA_W_23 , SET_INA_SH_23 ,
  SET_INA_LIM_23 , SET_INA_W_31 , SET_INA_SH_31 , SET_INA_LIM_31 ,
  SET_INA_W_32 , SET_INA_SH_32 , SET_INA_LIM_32 , SET_INA_W_33 ,
  SET_INA_SH_33 , SET_INA_LIM_33 , SET_INA_FIT_LAST = SET_INA_FIT_3 , SET_INA_CH_0 = SET_INA_W_01 ,
  SET_INA_CH_LAST = SET_INA_LIM_33 , SET_SUPPLY_V_MAX , SET_SUPPLY_I_MAX , SET_SUPPLY_V_START ,
  SET_SUPPLY_I_START , SET_SUPPLY_TRIP_I , SET_SUPPLY_TRIP_V , SET_SUPPLY_TRIP_MS ,
  SET_SUPPLY_CONFIRM_SLIDE , SET_SUPPLY_CONFIRM_KEYS , SET_SERVO_CURVE , SET_SERVO_TEST_HZ ,
  SET_SERVO_TEST_RANGE , SET_SERVO_LEN_BY , SET_SERVO_LEN_S , SET_SERVO_LEN_MOVES ,
  SET_SERVO_DWELL_MS , SET_SERVO_SETTLE_MS , SET_SERVO_STEP_48 , SET_SERVO_STEP_60 ,
  SET_SERVO_STEP_74 , SET_SERVO_STEP_84 , SET_SERVO_BROWNOUT , SET_SERVO_IDLE_MAX ,
  SET_SERVO_HOLD_MAX , SET_SERVO_TRAVEL_MAX_MS , SET_SERVO_STALL_A , SET_SERVO_REPORT ,
  SET_SERVO_PROG_V , SET_SERVO_PROG_I , SET_SERVO_PROG_WAIT , SET_SERVO_TARGET ,
  SET_SERVO_PORT_PWM , SET_HITEC_SERIES , SET_STICK_V , SET_STICK_I ,
  SET_STICK_BEEP_MIN , SET_STICK_GAP_MIN , SET_STICK_LONG , SET_STICK_LONG_MAX ,
  SET_STICK_GROUP_GAP , SET_STICK_ENTRY , SET_STICK_STORE , SET_STICK_OFF ,
  SET_STICK_SILENCE , SET_STICK_TIMEOUT , SET_STICK_THRESHOLD , SET_STICK_HYST ,
  SET_UPD_REMIND , SET_UPD_CHANNEL , SET_LOG_AUTO , SET_LOG_USER ,
  SETTING_COUNT
}
 Every setting's id, in schema order. More...
enum  setting_text_id_t { SET_TEXT_DUT_NAME = 0 , SET_TEXT_LOG_AUTO_DIR , SET_TEXT_LOG_USER_DIR , SETTING_TEXT_COUNT }

Functions

void settings_init (void)
void settings_set_store (const settings_store_t *store)
void settings_set_observer (settings_observer_fn fn)
void settings_set_text_observer (settings_text_observer_fn fn)
void settings_set_hold (settings_hold_fn fn)
bool settings_held (setting_id_t id)
 Whether id is held now: settings_set(), settings_adjust(), settings_reset() and settings_reset_all() leave it, and SETUP draws its row without keys.
void settings_set_armed (settings_armed_fn fn)
 Install who says whether the bench is ARMED, or NULL for a bench that is never ARMED. Asked at every change, as the hold is.
bool settings_safe_only (setting_id_t id)
 Whether id changes on a SAFE bench only: held while the source settings_set_armed() installed says ARMED, as the throttle endpoints on MOTOR & ESC > SETTINGS are locked while ARMED. Screen rotation, which moves every control under the finger.
const setting_def_t * settings_def (setting_id_t id)
bool settings_derived (setting_id_t id)
const char * settings_category_name (setting_cat_t cat)
 A category's name in English, from ui_text.def.
const char * settings_label (setting_id_t id)
 A setting's label in English, from ui_text.def.
const char * settings_help (setting_id_t id)
 A setting's help line in English, from ui_text.def.
int settings_option_list (setting_id_t id)
 Which option list a setting shows, so a language's options are found by it.
float settings_get (setting_id_t id)
int settings_get_int (setting_id_t id)
bool settings_get_bool (setting_id_t id)
void settings_set (setting_id_t id, float value)
void settings_adjust (setting_id_t id, int steps)
bool settings_cycles (setting_id_t id)
bool settings_sense_sda_valid (int gpio)
bool settings_tap_pin_valid (int gpio)
 Whether Tap pin takes gpio: an IOmcu GPIO the RP2350-CAN brings out and does not reserve, outbind_reserved_mask(), that is no ADC pin – the TONE page refuses GP26 to GP29 of the RP2350A and GP40 to GP47 of the RP2354B. That leaves 0, 1, 2, 4, 5, 6, 7 and 13 to 22. A pin an output, the supply or the sensor bus holds is not known here; the page refuses it and SETUP marks the row.
bool settings_pdmini_same_pin (void)
void settings_reset (setting_cat_t cat)
void settings_reset_all (void)
int settings_in_category (setting_cat_t cat, setting_id_t *out, int max)
int settings_decimals (setting_id_t id)
 The digits after the point a number of id is shown and typed with: as many as its step has.
const char * settings_value_text (setting_id_t id, char *buf, size_t n)
 Render the value as it should appear on screen, unit excluded: a float with settings_decimals() digits after the point.
const char * settings_value_text_of (setting_id_t id, float value, char *buf, size_t n)
 Render value as settings_value_text() renders the value of id.
setting_cat_t settings_text_category (setting_text_id_t id)
int settings_texts_in_category (setting_cat_t cat, setting_text_id_t *out, int max)
const char * settings_text (setting_text_id_t id)
const char * settings_text_key (setting_text_id_t id)
void settings_set_text (setting_text_id_t id, const char *text)
const settings_store_t * settings_nvs_store (void)
bool settings_dirty (void)
float settings_stored (setting_id_t id)
const char * settings_stored_text (setting_text_id_t id)
bool settings_differs (setting_id_t id)
bool settings_text_differs (setting_text_id_t id)
int settings_changes (void)
int settings_discard (void)
bool settings_save (void)
bool settings_save_failed (void)
void settings_request_save (void)
bool settings_save_asked (void)
bool settings_save_tick (bool safe)
void settings_cancel_save (void)

Detailed Description

Device settings: a typed schema, a value per entry, and a persistence seam.

The schema carries range, step and unit, so the settings screen is generic – it renders whatever the table says rather than hard-coding a control per option. Adding a setting is one table row, and its label and help line are two entries of ui_text.def (shared/text), with every language.

Pure C. Persistence is a pair of function pointers, so the host tests use memory and the firmware uses NVS (non-volatile storage) without the model knowing the difference.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ SET_CAT_SETUP_COUNT

#define SET_CAT_SETUP_COUNT   SET_CAT_ESC

The categories SETUP opens from its tiles, which come first. SET_CAT_ESC is edited on MOTOR & ESC > SETTINGS, SET_CAT_SUPPLY, SET_CAT_SERVO and SET_CAT_STICK on their own screens, beside what they set, and SET_CAT_UPDATE on the UPDATES screen a SETUP tile opens.

◆ SET_INA_CH_ROWS

#define SET_INA_CH_ROWS   3

a channel's rows: WATCHES, SHUNT, LIMIT

◆ SET_INA_CHANNELS

#define SET_INA_CHANNELS   12

channels, three a part

◆ SET_INA_PARTS

#define SET_INA_PARTS   4

The INA3221 parts SETUP > SENSORS sets up: four, at 0x40 to 0x43, three channels each, and the rows a channel has: WATCHES, SHUNT and LIMIT (settings_sensors.h).

INA3221 parts, 0x40 to 0x43

Typedef Documentation

◆ settings_armed_fn

typedef bool(*) settings_armed_fn(void)

Who says whether the bench is ARMED now.

Returns
True while ARMED.

◆ settings_hold_fn

typedef bool(*) settings_hold_fn(setting_id_t id)

Whether a setting is held: something in use depends on the value as it is.

◆ settings_observer_fn

typedef void(*) settings_observer_fn(setting_id_t id)

Called after any value actually changes, so the app can act on it.

◆ settings_text_observer_fn

typedef void(*) settings_text_observer_fn(setting_text_id_t id)

Called after a string actually changes, as settings_observer_fn is for a value: an edit, a discard, a reset and the load at start-up.

Enumeration Type Documentation

◆ setting_cat_t

Enumerator
SET_CAT_APP 

theme, brightness, rotation, language, units, time zone, plot

SET_CAT_IFACE 

the sensors that plug into the bench

SET_CAT_CARD 

the SD card: which logs are written

SET_CAT_SENSORS 

the INA3221 parts: fitted, shunts, what each channel watches (settings_sensors.h)

SET_CAT_ESC 

pack, motor, telemetry, throttle output

SET_CAT_SUPPLY 

the SUPPLY screen's limits and start

SET_CAT_SERVO 

the SERVO screen's test and its limits

SET_CAT_STICK 

stick programming: supply and timing

SET_CAT_UPDATE 

the release reminder and the releases a check offers, on SETUP's UPDATES

◆ setting_id_t

Every setting's id, in schema order.

Enumerator
SET_INA_CH_0 

channel 0's first row

◆ setting_text_id_t

Enumerator
SET_TEXT_DUT_NAME 

the device under test, for the report

SET_TEXT_LOG_AUTO_DIR 

AUTO LOG FOLDER: the automatic logs'

SET_TEXT_LOG_USER_DIR 

USER LOG FOLDER: the tests' files

Function Documentation

◆ settings_adjust()

void settings_adjust ( setting_id_t id,
int steps )

Step by steps increments. A number stops at its range's ends. Booleans and enums cycle (settings_cycles()), except the INA228 and INA3221 addresses, which stop at the first and the last of their list. Sensor SDA steps from one value settings_sense_sda_valid() takes to the next and stops at the first and the last. PD mini TX and PD mini RX step over the GPIO the other holds, so a step never sets them to one pin; with that GPIO at the end of the range the step stays where it is. -1, not wired, is a step for both.

◆ settings_cancel_save()

void settings_cancel_save ( void )

Forget a request that has not been taken.

◆ settings_category_name()

const char * settings_category_name ( setting_cat_t cat)

A category's name in English, from ui_text.def.

Parameters
catThe category.
Returns
Its name; "" for one out of range. ui_setting_category() gives it in the language showing.

◆ settings_changes()

int settings_changes ( void )

How many values and strings differ from their stored ones.

◆ settings_cycles()

bool settings_cycles ( setting_id_t id)

Whether settings_adjust() wraps id round from one end to the other: a switch or a choice, drawn with < and > keys. False for a number and for the monitors' addresses, which stop at their ends and are drawn with - and + keys; false for an id out of range.

◆ settings_decimals()

int settings_decimals ( setting_id_t id)

The digits after the point a number of id is shown and typed with: as many as its step has.

Parameters
idThe setting.
Returns
0 for a step of 1 or more, 1 for 0.1, 2 for 0.05, 0.02 and 0.01, 3 for 0.001; 0 for an id out of range and a step of 0.

◆ settings_derived()

bool settings_derived ( setting_id_t id)

Whether id follows another setting: settings_set() and settings_adjust() leave it, and SETUP draws its row without keys. Sensor SCL, which is the GPIO after Sensor SDA.

◆ settings_differs()

bool settings_differs ( setting_id_t id)

Whether the value of id in force differs from its stored value.

◆ settings_dirty()

bool settings_dirty ( void )

Whether the values in force differ from the stored copy, or the copy is not known to be the medium: true after a refused save until a save succeeds. An edit back to the stored value leaves it false.

◆ settings_discard()

int settings_discard ( void )

Put every changed value and string back to its stored one, by settings_set() and settings_set_text(): the observer hears each value that moves as it hears an edit by hand, in schema order. A held value is left, as settings_set() leaves it; a derived one follows its source. After a refused save, when the medium can hold part of that write, it also asks for a save (settings_request_save()), so a restart loads the values put back. Returns how many values and strings still differ: the held ones.

◆ settings_held()

bool settings_held ( setting_id_t id)

Whether id is held now: settings_set(), settings_adjust(), settings_reset() and settings_reset_all() leave it, and SETUP draws its row without keys.

The servo tester's target and the port's pulse while the servo programmer holds the port (kst_panel.h); a SAFE-only setting while the bench is ARMED (settings_safe_only()).

Parameters
idThe setting.
Returns
True while held; false for an id out of range.

◆ settings_help()

const char * settings_help ( setting_id_t id)

A setting's help line in English, from ui_text.def.

Parameters
idThe setting.
Returns
Its help line, "" for none and for an id out of range. ui_setting_help() gives it in the language showing.

◆ settings_in_category()

int settings_in_category ( setting_cat_t cat,
setting_id_t * out,
int max )

Ids in a category, in schema order. Returns how many there are.

◆ settings_init()

void settings_init ( void )

Reset to defaults, then load from the store if one is set.

◆ settings_label()

const char * settings_label ( setting_id_t id)

A setting's label in English, from ui_text.def.

Parameters
idThe setting.
Returns
Its label; "" for an id out of range. ui_setting_label() gives it in the language showing.

◆ settings_nvs_store()

const settings_store_t * settings_nvs_store ( void )

NVS-backed store; pass to settings_set_store() before settings_init().

◆ settings_option_list()

int settings_option_list ( setting_id_t id)

Which option list a setting shows, so a language's options are found by it.

Parameters
idThe setting.
Returns
The list's place among the UI_OPTIONS() of ui_text.def, counted from 0; -1 for a setting that is no choice and for an id out of range.

◆ settings_pdmini_same_pin()

bool settings_pdmini_same_pin ( void )

Whether PD mini TX and PD mini RX hold one GPIO, 0 or above. The steps never set that; a stored set-up can hold it. The panel writes such a wiring to the SUPPLY page disabled (supply_link.c), so the PD mini stays off, and SETUP marks both rows.

◆ settings_request_save()

void settings_request_save ( void )

Ask for the values to be written, without writing them.

A save is a flash write, and on the panel a flash write disables the cache and stalls both cores: the task that beats the safety line does not run for its duration. So the operator says when they want it kept and the application says when that is survivable, which is the same split the IOmcu's own store already makes.

◆ settings_reset()

void settings_reset ( setting_cat_t cat)

Restore one category, or all of them, to the schema defaults: its values and its strings (settings_text_category()).

◆ settings_safe_only()

bool settings_safe_only ( setting_id_t id)

Whether id changes on a SAFE bench only: held while the source settings_set_armed() installed says ARMED, as the throttle endpoints on MOTOR & ESC > SETTINGS are locked while ARMED. Screen rotation, which moves every control under the finger.

Whether id changes on a SAFE bench only (settings.h).

Parameters
idThe setting.
Returns
True for SET_SCREEN_ROT.

Whether id changes on a SAFE bench only: held while the source settings_set_armed() installed says ARMED, as the throttle endpoints on MOTOR & ESC > SETTINGS are locked while ARMED. Screen rotation, which moves every control under the finger.

◆ settings_save()

bool settings_save ( void )

Persist through the store and clear the dirty flag.

◆ settings_save_asked()

bool settings_save_asked ( void )

Whether a save has been asked for and not yet taken.

◆ settings_save_failed()

bool settings_save_failed ( void )

Whether the last attempt failed and nothing has been written since.

◆ settings_save_tick()

bool settings_save_tick ( bool safe)

Take the save if one was asked for and safe says now will do.

Returns true when it wrote. Call it wherever the application knows the bench is idle – an armed bench is not the moment to stop both cores.

◆ settings_sense_sda_valid()

bool settings_sense_sda_valid ( int gpio)

Whether Sensor SDA takes gpio: -1, the bus's pins not set, or an IOmcu GPIO the sensor bus can have its SDA on with SCL on the GPIO after it. That is one I2C block's pair, link_sn_pins_pair() – the rule the IOmcu's SENSE page judges a write by – on two pins the RP2350-CAN brings out and does not reserve, outbind_reserved_mask(): the mask the IOmcu reserves at boot. 0, 4, 6, 14, 16, 18, 20 and 26. A pin an output, the supply or the phase tap holds is not known here; the page refuses it and SETUP marks the row.

◆ settings_set()

void settings_set ( setting_id_t id,
float value )

Clamped to the schema; enums wrap. Fires the observer when it changes. A derived setting and a held one are left as they are.

◆ settings_set_armed()

void settings_set_armed ( settings_armed_fn fn)

Install who says whether the bench is ARMED, or NULL for a bench that is never ARMED. Asked at every change, as the hold is.

Install the ARMED source (settings.h).

Parameters
fnThe source; the panel's reads the router's status.

Install who says whether the bench is ARMED, or NULL for a bench that is never ARMED. Asked at every change, as the hold is.

◆ settings_set_hold()

void settings_set_hold ( settings_hold_fn fn)

Who says which settings are held, or NULL for none. Asked at every change, so a hold begins and ends with what it names.

◆ settings_set_text()

void settings_set_text ( setting_text_id_t id,
const char * text )

Set it, cut to SETTINGS_TEXT_MAX - 1 characters; an edit like any other.

◆ settings_stored()

float settings_stored ( setting_id_t id)

The stored value of id; 0 for an id out of range.

◆ settings_stored_text()

const char * settings_stored_text ( setting_text_id_t id)

The stored string of id; "" for an id out of range. Never NULL.

◆ settings_tap_pin_valid()

bool settings_tap_pin_valid ( int gpio)

Whether Tap pin takes gpio: an IOmcu GPIO the RP2350-CAN brings out and does not reserve, outbind_reserved_mask(), that is no ADC pin – the TONE page refuses GP26 to GP29 of the RP2350A and GP40 to GP47 of the RP2354B. That leaves 0, 1, 2, 4, 5, 6, 7 and 13 to 22. A pin an output, the supply or the sensor bus holds is not known here; the page refuses it and SETUP marks the row.

Parameters
gpioAn IOmcu GPIO number.
Returns
true when Tap pin takes it.

◆ settings_text()

const char * settings_text ( setting_text_id_t id)

A string setting. Never NULL.

◆ settings_text_category()

setting_cat_t settings_text_category ( setting_text_id_t id)

The category a string is set in on SETUP, or SET_CAT_COUNT for one set elsewhere: the DUT name, on SERVO > SETTINGS.

◆ settings_text_differs()

bool settings_text_differs ( setting_text_id_t id)

Whether the string of id differs from its stored string.

◆ settings_text_key()

const char * settings_text_key ( setting_text_id_t id)

Its NVS key, 15 characters or fewer. NULL for an id out of range.

◆ settings_texts_in_category()

int settings_texts_in_category ( setting_cat_t cat,
setting_text_id_t * out,
int max )

The strings of cat, in id order. Returns how many there are.

◆ settings_value_text()

const char * settings_value_text ( setting_id_t id,
char * buf,
size_t n )

Render the value as it should appear on screen, unit excluded: a float with settings_decimals() digits after the point.

Parameters
idThe setting.
bufWhere the text goes.
nThe size of buf in bytes.
Returns
buf; "" for a NULL buf or an n of 0.

◆ settings_value_text_of()

const char * settings_value_text_of ( setting_id_t id,
float value,
char * buf,
size_t n )

Render value as settings_value_text() renders the value of id.

Parameters
idThe setting.
valueThe value.
bufWhere the text goes.
nIts size.
Returns
buf; "" for no buffer.