Fork me on GitHub

Configuration infrastructure

The detailed description of the configuration infrastrucuture is given in the dedicated documentation section . This document covers configuration API for both C/C++ and JavaScript.

C API Reference mgos_config.h

#include "mgos_config.h"

See on GitHub: mgos_config.h, mgos_config.c

The usage pattern is this:

  1. Create an empty config struct at the beginning.
  2. Load the defaults.
  3. Then, apply overrides.

When override is applied, previously allocated values are freed.


bool mgos_conf_check_access(const struct mg_str key, const char *acl);

bool mgos_conf_check_access_n(const struct mg_str key, struct mg_str acl);

enum mgos_conf_type {
  CONF_TYPE_INT = 0,
  CONF_TYPE_BOOL = 1,
  CONF_TYPE_DOUBLE = 2,
  CONF_TYPE_STRING = 3,
  CONF_TYPE_OBJECT = 4,
};

struct mgos_conf_entry {
  enum mgos_conf_type type;
  const char *key;
  union {
    int offset;
    int num_desc;
  };

bool mgos_conf_parse(const struct mg_str json, const char *acl,
                     const struct mgos_conf_entry *schema, void *cfg);

Parses config in 'json' into 'cfg' according to rules defined in 'schema' and checking keys against 'acl'.

typedef void (*mgos_conf_emit_cb_t)(struct mbuf *data, void *param);

Emit config in 'cfg' according to rules in 'schema'. Keys are only emitted if their values are different from 'base'. If 'base' is NULL then all keys are emitted.

void mgos_conf_emit_cb(const void *cfg, const void *base,
                       const struct mgos_conf_entry *schema, bool pretty,
                       struct mbuf *out, mgos_conf_emit_cb_t cb,
                       void *cb_param);

bool mgos_conf_emit_f(const void *cfg, const void *base,
                      const struct mgos_conf_entry *schema, bool pretty,
                      const char *fname);

void mgos_conf_free(const struct mgos_conf_entry *schema, void *cfg);

Frees any resources allocated in 'cfg'.

const struct mgos_conf_entry *mgos_conf_find_schema_entry(
    const char *path, const struct mgos_conf_entry *obj);

const struct mgos_conf_entry *mgos_conf_find_schema_entry_s(
    const struct mg_str path, const struct mgos_conf_entry *obj);

void mgos_conf_set_str(char **vp, const char *v);

enum mgos_conf_type mgos_conf_value_type(struct mgos_conf_entry *e);

Returns a type of the value (this function is primarily for FFI)

const char *mgos_conf_value_string(const void *cfg,
                                   const struct mgos_conf_entry *e);

Returns a string value from the config entry. If the value is empty, returns NULL.

const char *mgos_conf_value_string_nonnull(const void *cfg,
                                           const struct mgos_conf_entry *e);

Same as mgos_conf_value_string(), but returns an empty string instead of NULL when the value is empty.

int mgos_conf_value_int(const void *cfg, const struct mgos_conf_entry *e);

Returns an int or bool value from the config entry

double mgos_conf_value_double(const void *cfg, const struct mgos_conf_entry *e);

Returns a double value from the config entry

C API Reference mgos_sys_config.h

#include "mgos_sys_config.h"


enum mgos_config_level {
  MGOS_CONFIG_LEVEL_DEFAULTS = 0,
  MGOS_CONFIG_LEVEL_VENDOR_1 = 1,
  MGOS_CONFIG_LEVEL_VENDOR_2 = 2,
  MGOS_CONFIG_LEVEL_VENDOR_3 = 3,
  MGOS_CONFIG_LEVEL_VENDOR_4 = 4,
  MGOS_CONFIG_LEVEL_VENDOR_5 = 5,
  MGOS_CONFIG_LEVEL_VENDOR_6 = 6,
  MGOS_CONFIG_LEVEL_VENDOR_7 = 7,
  MGOS_CONFIG_LEVEL_VENDOR_8 = 8,
  MGOS_CONFIG_LEVEL_USER = 9,
};

struct sys_config *get_cfg(void);

Returns global instance of the config. Note: Will return NULL before mgos_sys_config_init.

bool save_cfg(const struct sys_config *cfg, char **msg);

Save config. Performs diff against defaults and only saves diffs. Reboot is required to reload the config. If return value is false, a message may be provided in *msg. If non-NULL, it must be free()d. It is safe to pass a NULL msg

bool load_config_defaults(struct sys_config *cfg);

Reset all config values to defaults.

void mgos_config_reset(int level);

Reset config down to and including |level|. 0 - defaults, 1-8 - vendor levels, 9 - user. mgos_config_reset(MGOS_CONFIG_LEVEL_USER) will wipe user settings.

typedef bool (*mgos_config_validator_fn)(const struct sys_config *cfg,
                                         char **msg);

Register a config validator. Validators will be invoked before saving config and if any of them returns false, config will not be saved. An error message may be msg may be set to error message. Note: if non-NULL, msg will be freed. Remember to use strdup and asprintf.

void mgos_register_config_validator(mgos_config_validator_fn fn);

const struct sys_ro_vars *get_ro_vars(void);

void device_get_mac_address(uint8_t mac[6]);

void mgos_expand_mac_address_placeholders(char *str);

Expands question marks in "str" with digits from the MAC address.

enum mgos_init_result mgos_sys_config_init(void);

bool mgos_config_apply(const char *sys_config_subset_json, bool save);

Apply a subset of system configuration. Return true on success.

bool mgos_config_apply_s(const struct mg_str, bool save);

Same as mgos_config_apply but uses mg_str

JAVASCRIPT API Reference api_config.js

load("api_config.js");


Cfg.get(path)

Get the config value by the configuration variable. Currently, only simple types are returned: strings, ints, booleans, doubles. Objects are not yet supported.

Examples:

load('api_config.js');
Cfg.get('device.id');        // returns a string
Cfg.get('debug.level');      // returns an integer
Cfg.get('wifi.sta.enable');  // returns a boolean

Cfg.set(obj, opt_save)

Set the configuration. obj must be a subset of the whole configuation tree. save is boolean flag that indicating whether the change should be saved - it could be omitted, in which case it defaults to true. Examples:

load('api_config.js');
Cfg.set({wifi: {ap: {enable: false}}});  // Disable WiFi AP mode
Cfg.set({debug: {level: 3}});            // Set debug level to 3