[FL-3057] Allow use of any suitable pin for 1-Wire devices (#2350)

* Add 1-wire thermometer example app stub
* Working 1-wire thermometer app
* Refactor app to use threads
* Clean up code, add comments
* Add CRC checking
* Increase update period
* Fix error in fbt
* Revert the old update period
* Use settable pin in onewire_host
* Use settable pin for onewire_slave
* Clear EXTI flag after callback, make private methods static in onewire_slave
* Do not hardcode GPIO pin number
* Remove iButton hal from furi_hal_rfid
* Remove most of furi_hal_ibutton
* Add some of furi_hal_ibutton back
* Slightly neater code
* Fix formatting
* Fix PVS-studio warnings
* Update CODEOWNERS
* Add furi_hal_gpio_get_ext_pin_number
* Create README.md
* FuriHal: move furi_hal_gpio_get_ext_pin_number to resources

---------

Co-authored-by: Aleksandr Kutuzov <alleteam@gmail.com>

applications/examples/example_thermo/README.md

@@ -0,0 +1,44 @@
+# 1-Wire Thermometer
+This example application demonstrates the use of the 1-Wire library with a DS18B20 thermometer. 
+It also covers basic GUI, input handling, threads and localisation.
+
+## Electrical connections
+Before launching the application, connect the sensor to Flipper's external GPIO according to the table below:
+| DS18B20 | Flipper |
+| :-----: | :-----: |
+| VDD | 9 |
+| GND | 18 |
+| DQ  | 17 |
+
+*NOTE 1*: GND is also available on pins 8 and 11.
+
+*NOTE 2*: For any other pin than 17, connect an external 4.7k pull-up resistor to pin 9.
+
+## Launching the application
+In order to launch this demo, follow the steps below:
+1. Make sure your Flipper has an SD card installed.
+2. Connect your Flipper to the computer via a USB cable.
+3. Run `./fbt launch_app APPSRC=example_thermo` in your terminal emulator of choice.
+
+## Changing the data pin
+It is possible to use other GPIO pin as a 1-Wire data pin. In order to change it, set the `THERMO_GPIO_PIN` macro to any of the options listed below:
+
+```c
+/* Possible GPIO pin choices:
+ - gpio_ext_pc0
+ - gpio_ext_pc1
+ - gpio_ext_pc3
+ - gpio_ext_pb2
+ - gpio_ext_pb3
+ - gpio_ext_pa4
+ - gpio_ext_pa6
+ - gpio_ext_pa7
+ - ibutton_gpio
+*/
+
+#define THERMO_GPIO_PIN (ibutton_gpio)
+```
+Do not forget about the external pull-up resistor as these pins do not have one built-in.
+
+With the changes been made, recompile and launch the application again. 
+The on-screen text should reflect it by asking to connect the thermometer to another pin.

applications/examples/example_thermo/application.fam

@@ -0,0 +1,10 @@
+App(
+    appid="example_thermo",
+    name="Example: Thermometer",
+    apptype=FlipperAppType.EXTERNAL,
+    entry_point="example_thermo_main",
+    requires=["gui"],
+    stack_size=1 * 1024,
+    fap_icon="example_thermo_10px.png",
+    fap_category="Examples",
+)

applications/examples/example_thermo/example_thermo.c

@@ -0,0 +1,356 @@
+/*
+ * This file contains an example application that reads and displays
+ * the temperature from a DS18B20 1-wire thermometer.
+ *
+ * It also covers basic GUI, input handling, threads and localisation.
+ *
+ * References:
+ * [1] DS18B20 Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf
+ */
+
+#include <gui/gui.h>
+#include <gui/view_port.h>
+
+#include <core/thread.h>
+#include <core/kernel.h>
+
+#include <locale/locale.h>
+
+#include <one_wire/maxim_crc.h>
+#include <one_wire/one_wire_host.h>
+
+#define UPDATE_PERIOD_MS 1000UL
+#define TEXT_STORE_SIZE 64U
+
+#define DS18B20_CMD_CONVERT 0x44U
+#define DS18B20_CMD_READ_SCRATCHPAD 0xbeU
+
+#define DS18B20_CFG_RESOLUTION_POS 5U
+#define DS18B20_CFG_RESOLUTION_MASK 0x03U
+#define DS18B20_DECIMAL_PART_MASK 0x0fU
+
+#define DS18B20_SIGN_MASK 0xf0U
+
+/* Possible GPIO pin choices:
+ - gpio_ext_pc0
+ - gpio_ext_pc1
+ - gpio_ext_pc3
+ - gpio_ext_pb2
+ - gpio_ext_pb3
+ - gpio_ext_pa4
+ - gpio_ext_pa6
+ - gpio_ext_pa7
+ - ibutton_gpio
+*/
+
+#define THERMO_GPIO_PIN (ibutton_gpio)
+
+/* Flags which the reader thread responds to */
+typedef enum {
+    ReaderThreadFlagExit = 1,
+} ReaderThreadFlag;
+
+typedef union {
+    struct {
+        uint8_t temp_lsb; /* Least significant byte of the temperature */
+        uint8_t temp_msb; /* Most significant byte of the temperature */
+        uint8_t user_alarm_high; /* User register 1 (Temp high alarm) */
+        uint8_t user_alarm_low; /* User register 2 (Temp low alarm) */
+        uint8_t config; /* Configuration register */
+        uint8_t reserved[3]; /* Not used */
+        uint8_t crc; /* CRC checksum for error detection */
+    } fields;
+    uint8_t bytes[9];
+} DS18B20Scratchpad;
+
+/* Application context structure */
+typedef struct {
+    Gui* gui;
+    ViewPort* view_port;
+    FuriThread* reader_thread;
+    FuriMessageQueue* event_queue;
+    OneWireHost* onewire;
+    float temp_celsius;
+    bool has_device;
+} ExampleThermoContext;
+
+/*************** 1-Wire Communication and Processing *****************/
+
+/* Commands the thermometer to begin measuring the temperature. */
+static void example_thermo_request_temperature(ExampleThermoContext* context) {
+    OneWireHost* onewire = context->onewire;
+
+    /* All 1-wire transactions must happen in a critical section, i.e
+       not interrupted by other threads. */
+    FURI_CRITICAL_ENTER();
+
+    bool success = false;
+    do {
+        /* Each communication with a 1-wire device starts by a reset.
+           The functon will return true if a device responded with a presence pulse. */
+        if(!onewire_host_reset(onewire)) break;
+        /* After the reset, a ROM operation must follow.
+           If there is only one device connected, the "Skip ROM" command is most appropriate
+           (it can also be used to address all of the connected devices in some cases).*/
+        onewire_host_skip(onewire);
+        /* After the ROM operation, a device-specific command is issued.
+           In this case, it's a request to start measuring the temperature. */
+        onewire_host_write(onewire, DS18B20_CMD_CONVERT);
+
+        success = true;
+    } while(false);
+
+    context->has_device = success;
+
+    FURI_CRITICAL_EXIT();
+}
+
+/* Reads the measured temperature from the thermometer. */
+static void example_thermo_read_temperature(ExampleThermoContext* context) {
+    /* If there was no device detected, don't try to read the temperature */
+    if(!context->has_device) {
+        return;
+    }
+
+    OneWireHost* onewire = context->onewire;
+
+    /* All 1-wire transactions must happen in a critical section, i.e
+       not interrupted by other threads. */
+    FURI_CRITICAL_ENTER();
+
+    bool success = false;
+
+    do {
+        DS18B20Scratchpad buf;
+
+        /* Attempt reading the temperature 10 times before giving up */
+        size_t attempts_left = 10;
+        do {
+            /* Each communication with a 1-wire device starts by a reset.
+            The functon will return true if a device responded with a presence pulse. */
+            if(!onewire_host_reset(onewire)) continue;
+
+            /* After the reset, a ROM operation must follow.
+            If there is only one device connected, the "Skip ROM" command is most appropriate
+            (it can also be used to address all of the connected devices in some cases).*/
+            onewire_host_skip(onewire);
+
+            /* After the ROM operation, a device-specific command is issued.
+            This time, it will be the "Read Scratchpad" command which will
+            prepare the device's internal buffer memory for reading. */
+            onewire_host_write(onewire, DS18B20_CMD_READ_SCRATCHPAD);
+
+            /* The actual reading happens here. A total of 9 bytes is read. */
+            onewire_host_read_bytes(onewire, buf.bytes, sizeof(buf.bytes));
+
+            /* Calculate the checksum and compare it with one provided by the device. */
+            const uint8_t crc = maxim_crc8(buf.bytes, sizeof(buf.bytes) - 1, MAXIM_CRC8_INIT);
+
+            /* Checksums match, exit the loop */
+            if(crc == buf.fields.crc) break;
+
+        } while(--attempts_left);
+
+        if(attempts_left == 0) break;
+
+        /* Get the measurement resolution from the configuration register. (See [1] page 9) */
+        const uint8_t resolution_mode = (buf.fields.config >> DS18B20_CFG_RESOLUTION_POS) &
+                                        DS18B20_CFG_RESOLUTION_MASK;
+
+        /* Generate a mask for undefined bits in the decimal part. (See [1] page 6) */
+        const uint8_t decimal_mask =
+            (DS18B20_DECIMAL_PART_MASK << (DS18B20_CFG_RESOLUTION_MASK - resolution_mode)) &
+            DS18B20_DECIMAL_PART_MASK;
+
+        /* Get the integer and decimal part of the temperature (See [1] page 6) */
+        const uint8_t integer_part = (buf.fields.temp_msb << 4U) | (buf.fields.temp_lsb >> 4U);
+        const uint8_t decimal_part = buf.fields.temp_lsb & decimal_mask;
+
+        /* Calculate the sign of the temperature (See [1] page 6) */
+        const bool is_negative = (buf.fields.temp_msb & DS18B20_SIGN_MASK) != 0;
+
+        /* Combine the integer and decimal part together */
+        const float temp_celsius_abs = integer_part + decimal_part / 16.f;
+
+        /* Set the appropriate sign */
+        context->temp_celsius = is_negative ? -temp_celsius_abs : temp_celsius_abs;
+
+        success = true;
+    } while(false);
+
+    context->has_device = success;
+
+    FURI_CRITICAL_EXIT();
+}
+
+/* Periodically requests measurements and reads temperature. This function runs in a separare thread. */
+static int32_t example_thermo_reader_thread_callback(void* ctx) {
+    ExampleThermoContext* context = ctx;
+
+    for(;;) {
+        /* Tell the termometer to start measuring the temperature. The process may take up to 750ms. */
+        example_thermo_request_temperature(context);
+
+        /* Wait for the measurement to finish. At the same time wait for an exit signal. */
+        const uint32_t flags =
+            furi_thread_flags_wait(ReaderThreadFlagExit, FuriFlagWaitAny, UPDATE_PERIOD_MS);
+
+        /* If an exit signal was received, return from this thread. */
+        if(flags != (unsigned)FuriFlagErrorTimeout) break;
+
+        /* The measurement is now ready, read it from the termometer. */
+        example_thermo_read_temperature(context);
+    }
+
+    return 0;
+}
+
+/*************** GUI, Input and Main Loop *****************/
+
+/* Draw the GUI of the application. The screen is completely redrawn during each call. */
+static void example_thermo_draw_callback(Canvas* canvas, void* ctx) {
+    ExampleThermoContext* context = ctx;
+    char text_store[TEXT_STORE_SIZE];
+    const size_t middle_x = canvas_width(canvas) / 2U;
+
+    canvas_set_font(canvas, FontPrimary);
+    canvas_draw_str_aligned(canvas, middle_x, 12, AlignCenter, AlignBottom, "Thermometer Demo");
+    canvas_draw_line(canvas, 0, 16, 128, 16);
+
+    canvas_set_font(canvas, FontSecondary);
+    canvas_draw_str_aligned(
+        canvas, middle_x, 30, AlignCenter, AlignBottom, "Connnect thermometer");
+
+    snprintf(
+        text_store,
+        TEXT_STORE_SIZE,
+        "to GPIO pin %ld",
+        furi_hal_resources_get_ext_pin_number(&THERMO_GPIO_PIN));
+    canvas_draw_str_aligned(canvas, middle_x, 42, AlignCenter, AlignBottom, text_store);
+
+    canvas_set_font(canvas, FontKeyboard);
+
+    if(context->has_device) {
+        float temp;
+        char temp_units;
+
+        /* The applicaton is locale-aware.
+           Change Settings->System->Units to check it out. */
+        switch(locale_get_measurement_unit()) {
+        case LocaleMeasurementUnitsMetric:
+            temp = context->temp_celsius;
+            temp_units = 'C';
+            break;
+        case LocaleMeasurementUnitsImperial:
+            temp = locale_celsius_to_fahrenheit(context->temp_celsius);
+            temp_units = 'F';
+            break;
+        default:
+            furi_crash("Illegal measurement units");
+        }
+        /* If a reading is available, display it */
+        snprintf(text_store, TEXT_STORE_SIZE, "Temperature: %+.1f%c", (double)temp, temp_units);
+    } else {
+        /* Or show a message that no data is available */
+        strncpy(text_store, "-- No data --", TEXT_STORE_SIZE);
+    }
+
+    canvas_draw_str_aligned(canvas, middle_x, 58, AlignCenter, AlignBottom, text_store);
+}
+
+/* This function is called from the GUI thread. All it does is put the event
+   into the application's queue so it can be processed later. */
+static void example_thermo_input_callback(InputEvent* event, void* ctx) {
+    ExampleThermoContext* context = ctx;
+    furi_message_queue_put(context->event_queue, event, FuriWaitForever);
+}
+
+/* Starts the reader thread and handles the input */
+static void example_thermo_run(ExampleThermoContext* context) {
+    /* Configure the hardware in host mode */
+    onewire_host_start(context->onewire);
+
+    /* Start the reader thread. It will talk to the thermometer in the background. */
+    furi_thread_start(context->reader_thread);
+
+    /* An endless loop which handles the input*/
+    for(bool is_running = true; is_running;) {
+        InputEvent event;
+        /* Wait for an input event. Input events come from the GUI thread via a callback. */
+        const FuriStatus status =
+            furi_message_queue_get(context->event_queue, &event, FuriWaitForever);
+
+        /* This application is only interested in short button presses. */
+        if((status != FuriStatusOk) || (event.type != InputTypeShort)) {
+            continue;
+        }
+
+        /* When the user presses the "Back" button, break the loop and exit the application. */
+        if(event.key == InputKeyBack) {
+            is_running = false;
+        }
+    }
+
+    /* Signal the reader thread to cease operation and exit */
+    furi_thread_flags_set(furi_thread_get_id(context->reader_thread), ReaderThreadFlagExit);
+
+    /* Wait for the reader thread to finish */
+    furi_thread_join(context->reader_thread);
+
+    /* Reset the hardware */
+    onewire_host_stop(context->onewire);
+}
+
+/******************** Initialisation & startup *****************************/
+
+/* Allocate the memory and initialise the variables */
+static ExampleThermoContext* example_thermo_context_alloc() {
+    ExampleThermoContext* context = malloc(sizeof(ExampleThermoContext));
+
+    context->view_port = view_port_alloc();
+    view_port_draw_callback_set(context->view_port, example_thermo_draw_callback, context);
+    view_port_input_callback_set(context->view_port, example_thermo_input_callback, context);
+
+    context->event_queue = furi_message_queue_alloc(8, sizeof(InputEvent));
+
+    context->reader_thread = furi_thread_alloc();
+    furi_thread_set_stack_size(context->reader_thread, 1024U);
+    furi_thread_set_context(context->reader_thread, context);
+    furi_thread_set_callback(context->reader_thread, example_thermo_reader_thread_callback);
+
+    context->gui = furi_record_open(RECORD_GUI);
+    gui_add_view_port(context->gui, context->view_port, GuiLayerFullscreen);
+
+    context->onewire = onewire_host_alloc(&THERMO_GPIO_PIN);
+
+    return context;
+}
+
+/* Release the unused resources and deallocate memory */
+static void example_thermo_context_free(ExampleThermoContext* context) {
+    view_port_enabled_set(context->view_port, false);
+    gui_remove_view_port(context->gui, context->view_port);
+
+    onewire_host_free(context->onewire);
+    furi_thread_free(context->reader_thread);
+    furi_message_queue_free(context->event_queue);
+    view_port_free(context->view_port);
+
+    furi_record_close(RECORD_GUI);
+}
+
+/* The application's entry point. Execution starts from here. */
+int32_t example_thermo_main(void* p) {
+    UNUSED(p);
+
+    /* Allocate all of the necessary structures */
+    ExampleThermoContext* context = example_thermo_context_alloc();
+
+    /* Start the applicaton's main loop. It won't return until the application was requested to exit. */
+    example_thermo_run(context);
+
+    /* Release all unneeded resources */
+    example_thermo_context_free(context);
+
+    return 0;
+}