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/Input-API.md
+++ b/wiki/fw/api/Input-API.md
@@ -0,0 +1,107 @@
+All input API available by struct:
+
+```C
+typedef struct {
+    Subscriber* events; /// debounced keyboards events: press/release, Subscriber<InputEvent*>
+    Subscriber* raw_events; /// raw keyboards events: press/release, Subscriber<InputEvent*>
+    ValueMutex* state; /// current keyboard state, ValueMutex<InputState*>
+} Input;
+```
+
+You can get API instance by calling `open_input`:
+
+```C
+/// Get input struct
+inline Input* open_input(const char* name) {
+    return (Input*)furi_open(name);
+}
+```
+
+Default (system) input name is `/dev/kb`.
+
+Buttons state store as struct:
+
+```C
+/// Current state of buttons
+typedef struct {
+    bool up;
+    bool down;
+    bool right;
+    bool left;
+    bool ok;
+    bool back;
+} InputState;
+```
+
+To read buttons state you should use `read_state` function:
+
+```C
+/// read current state of all buttons. Return true if success, false otherwise
+inline bool read_state(Input* api, InputState* value, uint32_t timeout) {
+    return read_mutex(api->state, (void*)value, sizeof(InputState), timeout);
+}
+```
+
+Also you can subscribe to input events:
+
+```C
+/// used to pass button press/release evens
+typedef struct {
+    Inputs input; /// what button
+    bool state; /// true = press, false = release
+} InputEvent;
+
+/// List of buttons
+typedef enum {
+    InputsUp = 0,
+    InputsDown,
+    InputsRight,
+    InputsLeft,
+    InputsOk,
+    InputsBack,
+    InputsSize
+} Inputs;
+```
+
+Use `subscribe_input_events` to register your callback:
+
+```C
+/// subscribe on button press/release events. Return true if success, false otherwise
+inline bool subscribe_input_events(Subscriber* events, void(*cb)(InputEvent*, void*), void* ctx) {
+    return subscribe_pubsub(events, void(*)(void*, void*)(cb), ctx);
+}
+```
+
+## Usage example
+
+```C
+// function used to handle keyboard events
+void handle_keyboard(InputEvent* event, void* _ctx) {
+    if(event->state) {
+        printf("you press %d", event->input);
+    } else {
+        printf("you release %d", event->input);
+    }
+}
+
+void input_example(void* p) {
+    Input* input = open_input("/dev/kb");
+    if(input == NULL) return; // keyboard not available, critical error
+
+    // async way
+    subscribe_input_events(input->events, handle_keyboard, NULL);
+
+    // blocking way
+    InputState state;
+    while(1) {
+        if(read_state(input, &state, OsWaitForever)) {
+            if(state.up) {
+                printf("up is pressed");
+                delay(1000);
+            }
+        }
+
+        delay(10);
+    }
+}
+```