Sys Runtime Configuration Registry

examples/registry_cli/Makefile

@@ -0,0 +1,38 @@
+# name of the application
+APPLICATION = registry_example_cli
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= native
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../..
+
+# required modules
+# enable the shell to execute the registry CLI
+USEMODULE += shell
+USEMODULE += shell_cmds_default
+
+# enable littlefs2 for the persistent storage of the registry
+USEMODULE += littlefs2
+# enable mtd to use it as the storage location
+USEMODULE += mtd
+
+# enable the string_path extension of the registry to
+# identify configuration parameters using strings instead of pointers
+USEMODULE +=  registry_string_path
+# enable the vfs storage implementation to persistently store configuration
+# parameters to a storage device such as the mtd
+USEMODULE +=  registry_storage_vfs
+# enable the rgb_led schema (sys/rgb_led) to demonstrate how to configure 
+# RGB LEDs as an example for the registry CLI
+USEMODULE +=  registry_namespace_sys_rgb_led
+
+# Comment this out to disable code in RIOT that does safety checking
+# which is not needed in a production environment but helps in the
+# development process:
+DEVELHELP ?= 1
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include

examples/registry_cli/README.md

@@ -0,0 +1,25 @@
+examples/registry_cli
+================
+
+This application demonstrates the most basic usage of the RIOT Registry.
+
+Usage
+=====
+
+Simply build and flash the application for your target board:
+
+```
+BOARD=YOUR_BOARD_NAME_HERE make flash term
+```
+
+Now you should have access to the RIOT shell on your board. For interacting
+with the RIOT Registry, use the `registry` shell command, e.g.:
+
+```
+registry export         <- prints the IDs of the whole configuration tree
+registry get 0/0/0/0    <- get the value of the red parameter of the instance 0 of the RGB LED Schema inside of the SYS namespace
+registry set 0/0/0/0 56 <- set the value of the red parameter to 56
+registry commit 0/0/0/0 <- apply new value for the 0/0/0/0 path
+registry save           <- save configurations to persistent storage
+registry load           <- load configurations from persistent storage
+```

examples/registry_cli/main.c

@@ -0,0 +1,161 @@
+/*
+ * Copyright (C) 2023 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       RIOT registry CLI example application to demonstrate how
+ *              to use the RIOT registry using the CLI.
+ *
+ * @author      Lasse Rosenow <[email protected]>
+ *
+ * @}
+ */
+
+#include <string.h>
+#include <stdio.h>
+
+#include "msg.h"
+#include "shell.h"
+#include "board.h"
+#include "mtd.h"
+#include "vfs.h"
+#include "fs/littlefs2_fs.h"
+#include "registry.h"
+#include "registry/namespace/sys.h"
+#include "registry/namespace/sys/rgb_led.h"
+#include "registry/storage.h"
+#include "registry/string_path.h"
+
+/* this callback is usually implemented drivers such as an RGB LED driver */
+static registry_error_t shared_commit_cb(const registry_commit_cb_scope_t scope,
+                            const registry_group_or_parameter_id_t *group_or_parameter_id,
+                            const void *context)
+{
+    /* since this function is shared by multiple commit_cb functions, we path the instance in the context */
+    const registry_instance_t *instance = context;
+    const registry_sys_rgb_led_instance_t *data = instance->data;
+
+    printf("RGB instance commit_cb was executed on ");
+
+    /* check how much of the registry instance was committed and print the new values */
+    switch (scope)
+    {
+    case REGISTRY_COMMIT_INSTANCE:
+        /* in this case the whole instance and all parameters inside of it was committed */
+        printf("the whole instance: ID: %d\n", instance->id);
+        printf("\tParameter ID: 0, VALUE: %d\n", data->red);
+        printf("\tParameter ID: 1, VALUE: %d\n", data->green);
+        printf("\tParameter ID: 2, VALUE: %d\n", data->blue);
+        break;
+    case REGISTRY_COMMIT_GROUP:
+        /* in this case a group and all parameters inside of it was committed */
+        printf("a group: %d\n", *group_or_parameter_id);
+        /* this instance does not have groups, so no need to print anything here */
+        break;
+    case REGISTRY_COMMIT_PARAMETER:
+        /* in this case only a single parameter was committed */
+        printf("a single parameter: ID: %d,", *group_or_parameter_id);
+        switch (*group_or_parameter_id)
+        {
+        case 0: printf(" VALUE: %d\n", data->red); break;
+        case 1: printf(" VALUE: %d\n", data->green); break;
+        case 2: printf(" VALUE: %d\n", data->blue); break;
+        }
+    }
+
+    return REGISTRY_ERROR_NONE;
+}
+
+/* create instances of a configuration schema, to expose configuration parameters to the registry */
+static registry_error_t rgb_led_instance_0_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context);
+static registry_sys_rgb_led_instance_t rgb_led_instance_0_data = {
+    .red = 0,
+    .green = 255,
+    .blue = 70,
+};
+static registry_instance_t rgb_led_instance_0 = {
+    .name = "rgb-0",
+    .data = &rgb_led_instance_0_data,
+    .commit_cb = &rgb_led_instance_0_commit_cb,
+};
+static registry_error_t rgb_led_instance_0_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context) 
+{
+    (void)context;
+    return shared_commit_cb(scope, group_or_parameter_id, &rgb_led_instance_0);
+}
+
+/* create an instance for a second RGB LED */
+static registry_error_t rgb_led_instance_1_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context);
+static registry_sys_rgb_led_instance_t rgb_led_instance_1_data = {
+    .red = 90,
+    .green = 4,
+    .blue = 0,
+};
+static registry_instance_t rgb_led_instance_1 = {
+    .name = "rgb-1",
+    .data = &rgb_led_instance_1_data,
+    .commit_cb = &rgb_led_instance_1_commit_cb,
+};
+static registry_error_t rgb_led_instance_1_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context)
+{
+    (void)context;
+    return shared_commit_cb(scope, group_or_parameter_id, &rgb_led_instance_1);
+}
+
+/* configure the registry storage to use littlefs2 */
+static littlefs2_desc_t fs_desc = {
+    .lock = MUTEX_INIT,
+};
+
+/* set the mount point for the registry storage to /sda for this example */
+static vfs_mount_t _vfs_mount = {
+    .fs = &littlefs2_file_system,
+    .mount_point = "/sda",
+    .private_data = &fs_desc,
+};
+
+/* create a storage instance to register the storage at the RIOT registry */
+static registry_storage_instance_t vfs_instance = {
+    .storage = &registry_storage_vfs,
+    .data = &_vfs_mount,
+};
+
+int main(void)
+{
+    /* initialize the riot registry storage for persistent configuration parameters */
+    #if IS_USED(MODULE_LITTLEFS2)
+    fs_desc.dev = MTD_0;
+    #endif
+
+    /* initialize the riot registry */
+    registry_init();
+
+    /* set storage instances so that the CLI can find them */
+    const registry_storage_instance_t* storage_instances[] = {&vfs_instance};
+    registry_storage_set_instances(storage_instances);
+
+    /* add configuration schemas to the registry */
+    registry_add_schema_instance(&registry_sys_rgb_led, &rgb_led_instance_0);
+    registry_add_schema_instance(&registry_sys_rgb_led, &rgb_led_instance_1);
+
+    /* initialize and run the RIOT shell */
+    char line_buf[SHELL_DEFAULT_BUFSIZE];
+    shell_run(NULL, line_buf, sizeof(line_buf));
+    return 0;
+}

examples/registry_core/Makefile

@@ -0,0 +1,24 @@
+# name of the application
+APPLICATION = registry_example_core
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= native
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../..
+
+# required modules
+# enable board_led schema (sys/board_led) of the riot registry
+USEMODULE += registry_namespace_sys_board_led
+# enable the ztimer to turn the led on and off every second
+USEMODULE += ztimer_msec
+
+# Comment this out to disable code in RIOT that does safety checking
+# which is not needed in a production environment but helps in the
+# development process:
+DEVELHELP ?= 1
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include

examples/registry_core/README.md

@@ -0,0 +1,16 @@
+examples/registry_core
+================
+
+This application demonstrates the most basic usage of the RIOT Registry.
+It implements a RGB LED schema and continuously changes its value every second.
+
+Usage
+=====
+
+Simply build and flash the application for your target board:
+
+```
+BOARD=YOUR_BOARD_NAME_HERE make flash term
+```
+
+Now you should see the terminal continuously print out different LED states.

examples/registry_core/main.c

@@ -0,0 +1,108 @@
+/*
+ * Copyright (C) 2023 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       RIOT registry core minimal example application to demonstrate
+ *              how to use the riot registry without any of its extensions.
+ *
+ * @author      Lasse Rosenow <[email protected]>
+ *
+ * @}
+ */
+
+#include <string.h>
+#include <stdio.h>
+#include <unistd.h>
+
+#include "periph_cpu.h"
+#include "led.h"
+#include "board.h"
+#include "registry.h"
+#include "registry/namespace/sys.h"
+#include "registry/namespace/sys/board_led.h"
+#include "ztimer.h"
+
+registry_error_t board_led_instance_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context);
+
+/* This belongs into the BOARD or Driver for example */
+registry_sys_board_led_instance_t board_led_instance_0_data = {
+    .enabled = 0,
+};
+
+registry_instance_t board_led_instance = {
+    .data = &board_led_instance_0_data,
+    .commit_cb = &board_led_instance_commit_cb,
+};
+
+/* this callback is usually implemented drivers such as an RGB LED driver */
+registry_error_t board_led_instance_commit_cb(const registry_commit_cb_scope_t scope,
+                                 const registry_group_or_parameter_id_t *group_or_parameter_id,
+                                 const void *context)
+{
+    (void)scope;
+    (void)context;
+
+    /* Either commit all parameters of the instance or only the given parameter.
+     * For a single LED there is no difference as it only has one parameter. */
+    if ((group_or_parameter_id == NULL) ||
+        (*group_or_parameter_id == REGISTRY_SYS_BOARD_LED_ENABLED)) {
+        /* The Driver owns the board_led data instance, so we can just get our value from there */
+        bool led_state = board_led_instance_0_data.enabled;
+        /* Turn the LED on or off depending on the led_state */
+        if (led_state == true) {
+            /* This is the commit_cb function of instance 0, so we toggle LED 0 as well */
+            LED_ON(0);
+        } else {
+            LED_OFF(0);
+        }
+    }
+
+    return 0;
+}
+
+/* This belongs into our main application */
+int main(void)
+{
+    registry_init();
+
+    /* init schemas */
+    registry_add_schema_instance(&registry_sys_board_led, &board_led_instance);
+
+    bool board_led_enabled = false;
+
+    while (true) {
+        /* Invert the BOARD LED, to make it turn on and off on each subsequent cycle */
+        board_led_enabled = !board_led_enabled;
+
+        /* Create registry_node_t for the board_led_parameter */
+        const registry_node_t parameter_node = {
+            .type = REGISTRY_NODE_PARAMETER,
+            .value.parameter = {
+                .instance = &board_led_instance,
+                .parameter = &registry_sys_board_led_enabled,
+            },
+        };
+
+        /* Set new registry value */
+        registry_set(&parameter_node, &board_led_enabled, sizeof(board_led_enabled));
+
+        /* Apply the registry value to change the LED state (in this case calls the commit_cb function: "board_led_instance_commit_cb")*/
+        registry_commit(&parameter_node);
+
+        /* Sleep for 1 second and then do it again*/
+        ztimer_sleep(ZTIMER_MSEC, 1000);
+    }
+
+    return 0;
+}

makefiles/pseudomodules.inc.mk

@@ -406,6 +406,11 @@ PSEUDOMODULES += fortuna_reseed
 ##              will be removed after 2023.07 release.
 PSEUDOMODULES += random_cmd
 ## @}
+PSEUDOMODULES += registry_%
+NO_PSEUDOMODULES += registry_namespace_sys
+NO_PSEUDOMODULES += registry_namespace_tests
+NO_PSEUDOMODULES += registry_storage
+
 PSEUDOMODULES += riotboot_%
 PSEUDOMODULES += rtt_cmd
 PSEUDOMODULES += saul_adc
@@ -497,6 +502,7 @@ PSEUDOMODULES += shell_cmd_openwsn
 PSEUDOMODULES += shell_cmd_pm
 PSEUDOMODULES += shell_cmd_ps
 PSEUDOMODULES += shell_cmd_random
+PSEUDOMODULES += shell_cmd_registry
 PSEUDOMODULES += shell_cmd_rtc
 PSEUDOMODULES += shell_cmd_rtt
 PSEUDOMODULES += shell_cmd_saul_reg