Core api concept (#144)

* add input debounce code from old fw * exampl of input api * change input API to get/release * revert input API to read * pointer instead of instance * add input API description * add display API * rewrite display names * migrate to valuemanager * add LED API * add closing brakets * add sound api * fix led api * basic api * rename API pages * change pubsub implementation * move FURI AC -> flapp, add valuemutex example, add valuemanager implementation * pubsub usage example * user led example * update example * simplify input * add composed display * add SPI/GPIO and CC1101 bus * change cc1101 api * spi api and devices * spi api and devices * move SPI to page, add GPIO * not block pin open * backlight API and more * add minunit tests * fix logging * ignore unexisting time service on embedded targets * fix warning, issue with printf * Deprecate furi_open and furi_close (#167) Rename existing furi_open and furi_close to deprecated version * add exitcode * migrate to printf * indicate test by leds * add testing description * rename furi.h * wip basic api * add valuemutex, pubsub, split files * add value expanders * value mutex realization and tests * valuemutex test added to makefile * do not build unimplemented files * fix build furmware target f2 * redesigned minunit tests to allow testing in separate files * test file for valuemutex minunit testing * minunit partial test valuemutex * local cmsis_os2 mutex bindings * implement furi open/create, tests * migrate concurrent_access to ValueMutex * add spi header * Lib: add mlib submodule. Co-authored-by: rusdacent <rusdacentx0x08@gmail.com> Co-authored-by: DrZlo13 <who.just.the.doctor@gmail.com>
2020-10-13 14:22:43 +06:00
parent b7c30154f4
commit 942bbfaefe
51 changed files with 1874 additions and 692 deletions
--- a/wiki/fw/api/LED-API.md
+++ b/wiki/fw/api/LED-API.md
@@ -0,0 +1,110 @@
+LED state describes by struct:
+
+```C
+typedef struct {
+    uint8_t red;
+    uint8_t green;
+    uint8_t blue; 
+} Rgb;
+```
+
+LED API provided by struct:
+
+```C
+typedef struct {
+    ValueComposer* composer; /// every app add its value to compose, <Rgb*>
+    ValueManager* state; /// LED value state and changes <Rgb*>
+} LedApi;
+```
+
+You can get API instance by calling `open_led`:
+
+```C
+/// Add new layer to LED:
+inline LedApi* open_led(const char* name) {
+    return (LedApi*)furi_open(name);
+}
+```
+
+Default system led is `/dev/led`.
+
+To read current led state you should use `read_led` function:
+
+```C
+/// return true if success, false otherwise
+inline bool read_led(LedApi* led, Rgb* value, uint32_t timeout) {
+    return read_mutex(led->state->value, (void*)value, sizeof(Rgb), timeout);
+}
+```
+
+Also you can subscribe to led state changes:
+
+Use `subscribe_led_changes` to register your callback:
+
+```C
+/// return true if success, false otherwise
+inline bool subscribe_led_changes(LedApi* led, void(*cb)(Rgb*, void*), void* ctx) {
+    return subscribe_pubsub(led->state->pubsub, void(*)(void*, void*)(cb), ctx);
+}
+```
+
+Userspace helpers
+
+```C
+typedef struct {
+    Rgb value;
+    ValueMutex value_mutex;
+    ValueComposerHandle* composer_handle;
+} SystemLed;
+
+inline bool init_led_composer(SystemLed* led, LedApi* api, uint32_t layer) {
+    if(!init_mutex(&led->value_mutex, (void*)&led->value, sizeof(Rgb))) {
+        return false;
+    }
+    led->composer_handle = add_compose_layer(
+        api->composer, COPY_COMPOSE, &led->value_mutex, layer
+    ); // just copy led state on update
+
+    return led->composer_handle != NULL;
+}
+
+inline void write_led(SystemLed* led, Rgb* value) {
+    write_mutex(&led->value_mutex, (void*)value, sizeof(Rgb), OsWaitForever);
+    request_compose(led->composer_handle);
+}
+```
+
+
+## Usage example
+
+```C
+
+void handle_led_state(Rgb* rgb, void* _ctx) {
+    printf("led: #%02X%02X%02X\n", rgb->red, rgb->green, rgb->blue);
+}
+
+void led_example(void* p) {
+    LedApi* led_api = open_led("/dev/led");
+    if(led_api == NULL) return; // led not available, critical error
+
+    // subscribe to led state updates
+    subscribe_led_changes(led_api, handle_led_state, NULL);
+    // get current led value
+    Rgb led_value;
+    if(read_led(led_api, &led_value, OsWaitForever)) {
+        printf(
+            "initial led: #%02X%02X%02X\n",
+            led_value->red,
+            led_value->green,
+            led_value->blue
+        );
+    }
+
+    // create compose to control led
+    SystemLed system_led;
+    if(!init_led_composer(&system_led, led_api, UiLayerBelowNotify)) return;
+
+    // write RGB value
+    write_led(&system_led, &(Rgb{.red = 0xFA, green = 0xCE, .blue = 0x8D}));
+}
+```