From a8a2c5376d30c99ac2000d9610b12396ff61dc15 Mon Sep 17 00:00:00 2001 From: Derek Jamison Date: Wed, 25 Jan 2023 16:13:58 -0500 Subject: [PATCH] Add gpio_polling_demo tutorial --- README.md | 16 +- gpio/gpio_polling_demo/README.md | 96 +++++++++ gpio/gpio_polling_demo/application.fam | 10 + gpio/gpio_polling_demo/gpio_polling_demo.png | Bin 0 -> 1816 bytes .../gpio_polling_demo/gpio_polling_demo_app.c | 187 ++++++++++++++++++ 5 files changed, 305 insertions(+), 4 deletions(-) create mode 100644 gpio/gpio_polling_demo/README.md create mode 100644 gpio/gpio_polling_demo/application.fam create mode 100644 gpio/gpio_polling_demo/gpio_polling_demo.png create mode 100644 gpio/gpio_polling_demo/gpio_polling_demo_app.c diff --git a/README.md b/README.md index 761279a..96b1bb6 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,19 @@ I will use this repository for my Flipper Zero projects. The various README.md Feel free to reach out to me at CodeAllNight@outlook.com with any questions or leave them in the [issues section](https://github.com/jamisonderek/flipper-zero-tutorials/issues) for this project. -## firmware-updating +## Firmware +### firmware-updating [tutorial](./firmware/updating/README.md) - The Flipper Zero makes updating the firmware simple and fairly safe. It is easy to build your own firmware as well using the fbt command. -## subghz-protocol-x10-decoder + +## GPIO +### gpio-gpio-polling-demo +[tutorial](./gpio/gpio_polling_demo/README.md) - This is a "hello world" demonstration of reading a GPIO pin using polling. + + +## Subghz +### subghz-protocol-x10-decoder [project](./subghz/protocols/x10/README.md) - This is a protocol decoder for the Flipper Zero to decode the x10 series of devices when doing a read from the Sub-GHz menu. -## subghz-samples-quantum-fire -[data](./subghz/samples/quantum-fire/README.md) - These Flipper Zero subghz captures are from the remote control for the Quantum Fire (QF-6LR). \ No newline at end of file +### subghz-samples-quantum-fire +[data](./subghz/samples/quantum-fire/README.md) - These Flipper Zero subghz captures are from the remote control for the Quantum Fire (QF-6LR). diff --git a/gpio/gpio_polling_demo/README.md b/gpio/gpio_polling_demo/README.md new file mode 100644 index 0000000..1b5bbc5 --- /dev/null +++ b/gpio/gpio_polling_demo/README.md @@ -0,0 +1,96 @@ +# GPIO POLLING DEMO +## Introduction +This is a "hello world" demonstration of reading a GPIO pin using polling. For this demo, we connect a 1K resistor between pin GND (8) and pin A4 (4). When the resistor is not connected it says "Hello" and when connected it says "World". In theory you can use a wire, but I like to use a resistor in case I accidently run a demo that does GPIO output with the pins still connected. + + +## Installation Directions +This project is intended to be overlayed on top of an existing firmware repo. +- Clone, Build & Deploy an existing flipper zero firmware repo. See this [tutorial](/firmware/updating/README.md) for updating firmware. +- Copy the "gpio_polling_demo" [folder](..) to the \applications\plugins\gpio_polling_demo folder in your firmware. +- Build & deploy the firmware. See this [tutorial](/firmware/updating/README.md) for updating firmware. +- NOTE: You can also extract the gpio_polling_demo.FAP from resources.tar file and use qFlipper to copy the file to the SD Card/apps/Misc folder. + + +## Running the updated firmware +These directions assume you are starting at the flipper desktop. If not, please press the back button until you are at the desktop. + +- Press the OK button on the flipper to pull up the main menu. +- Choose "Applications" from the menu. +- Choose "Misc" from the sub-menu. +- Choose "Gpio Polling Demo" + +- The flipper should say "Hello". +- A counter should keep increasing and it should show if value is "Even" or "Odd". +- A tone should play. + +- Connect a 1K resistor between pin GND (8) and pin A4 (4). +- The message should change to "World". +- Remve the resistor and the message should change back to "Hello". + +- Press the BACK button to exit. + + +## How it works +- application.fam + - specifies the name of our application. + - specifies the entry point for our application. + - specifies we use the GUI. + - specifies our icon is the gpio_polling_demo.png file. + - specifies our application can be found in the "Misc" category. + +- gpio_polling_demo.png + - The icon for our application that shows up in the "Misc" folder. + +- gpio_polling_demo_app.c + - We #include the libraries we referece. + - We define DemoEventType (so we know the reason for events) + - We define DemoEvent (which has the event type and its data) used for adding to an event queue. + - We define DemoData (data used by our application) + - We define DemoContext (pointer to event queue, pointer to application data, and pointer to mutex [to safely access the data]) + - We define demo_message_pin for the GPIO pin that we will be using. + - We create a gpio_polling_demo_input_callback(...) method that queues a key event. + - We create a gpio_polling_demo_tick(...) method that queues a tick event. + - We create a gpio_polling_demo_render_callback(...) method that does the screen rendering. + - We acquire the mutex, so that no other thread can modify the data. + - If unsuccessful, we don't render anything this frame. + - From our context, we get the application data, setting "show_hello" to true if the pin was grounded when the data was last updated. + - From our context, we get the application data, setting "counter" to the counter from when the data was last updated. + - We set "even_counter" to true is the counter value is even, otherwise we set it to false. + - We select the Primary font. We render the text "Hello" (if pin was not grounded) or "World" (pin was grounded.) + - We put the lowest 4 digits of counter value into the data buffer + - We concatenate the text "Even" or "Odd" to the data buffer. + - We select the Secondary font. We render the data buffer. + - We release the mutex, so other threads may modify the data. + - We try to acquire the speaker. + - If the speaker is available, we play a tone with the frequency based on the counter. + - We create gpio_polling_demo_update_pin_status(...) method that updates out application data. + - We increment the counter. + - We use uri_hal_gpio_read(...) to get the status of the GPIO pin. <********* + - We create the entrypoint gpio_polling_demo_app(...) method + - We configure our initial data state + - We set demo_message_pin to gpio_ext_pa4. <********** + - For a different GPIO pin, see \firmware\targets\f7\furi_hal\furi_hal_resources.c + - We set the pin configuration <********** + - The mode of the pin is GpioModeInput (so it is an input pin) + - The pull of the pin is GpioPullUp (so it has VCC by default via a pullup-resistor) + - You can also use GpioPullDown (so it has GND by default via a pulldown-resistor) then connect resitior between the 3V3 pin (9) and A4 (4). + - You can also use GpioPullNo (so it is floating). Then you should provide your own pull-up/down resistor. + - We create a queue for events. + - We setup view_port_draw_callback_set(...) to invoke gpio_polling_demo_render_callback when rendering should happen. + - We setup view_port_input_callback_set(...) to invoke gpio_polling_demo_input_callback when button is pressed. + - We open GUI and register view_port. + - We setup furi_timer_alloc(...) to allocate a timer to ivoke gpio_polling_demo_tick on each tick. + - We start the timer with 250 millisecond ticks. + - We create a message pump loop + - We get an event from the queue. + - If it is key message. + - If it is a short press of back key, we set processing=false which will exit our message loop. + - If it is a tick message. + - We acquire the mutex. + - We invoke gpio_polling_demo_update_pin_status(...) to update the data, polling the GPIO pin. <********** + - We release the mutex. + - The message loop continues until processing is false. + - We set the GPIO pin to GpioPullNo (so that the pin is no longer set to GND or VCC.) + - We release the rest of our application resources. + - We exit the program. + \ No newline at end of file diff --git a/gpio/gpio_polling_demo/application.fam b/gpio/gpio_polling_demo/application.fam new file mode 100644 index 0000000..fc3d920 --- /dev/null +++ b/gpio/gpio_polling_demo/application.fam @@ -0,0 +1,10 @@ +App( + appid="gpio_polling_demo", + name="Gpio Polling Demo", + apptype=FlipperAppType.EXTERNAL, + entry_point="gpio_polling_demo_app", + requires=["gui"], + stack_size=2 * 1024, + fap_icon="gpio_polling_demo.png", + fap_category="Misc", +) diff --git a/gpio/gpio_polling_demo/gpio_polling_demo.png b/gpio/gpio_polling_demo/gpio_polling_demo.png new file mode 100644 index 0000000000000000000000000000000000000000..f893f75e6fa6e869cc2c153d91a569c1ccead892 GIT binary patch literal 1816 zcma)6eM}Q)7(XO3fuPyOCK9q-4xBn{?|M*>3$=l^LN^X8-|Ry?dT;4T+q>OeY552- z!sb^L*k%SuHW@=VG%RDX%qa+Nj))4&SeDE!V%#4ti*XW|&V_}&*Oreu_R-{e@B2Kz z=lA}e=Y8%uV9CvjiinLs5G2Z+ZOnsjWgW396#jpHN8f}XA+?;rU@;pEs72&$oC6@p z#_^*q>dr>-)Air}tf|Nr-E{-rjh0X3degUD~eOjospP>3h&W`^>2) zJfuEJHAojFhB04FbrF|iLh5FcHh-6eht6C+qQ5mTIhDWJeEPYfuKi;eM@IkrxVyA( z!=;nP?W0%o&ipZV?xStHg`u&#_YKz?xIuYOW$4xyPCOjs+uwcc=J|b})UB`Q*1W#c zgcqK<|BC(PhBv1VK0Ud2!fii0QC@TBC2_Rp`RhY zSLKr8{UiYzBao~jC&(P{LKRx3oOjDQ3@Y$R172>C+$9AH084=@9$cd)6tO<2VCQ9C zvh%`%m>~RuJ19uzZ2!Qoc!Hp?X3H~s8R1bNP5(R8>0FR4$)+lpaG-uclIMw~f@%Ta zc|hXbq7|5`fJ=_YP^AErfp_p?KI{UZ!!!Y#h4TVOiIH;xmjufS9mG;k=_8(n!uZK( zo`qaV7`kYOvm!7mbeNQvm5G{7h7?U&N{Wh9!$XxyQD!Go0djz=Lbm%4T(lN*Y>-h& z#Nk$MywJtL)X4xv$)ZDtrIPqOb?M*j@GdACb}GxrjFFL{V3L4+rXf`%Q9x*^WRlWo z6Nxm6fT{byJj>at{|oBtZWR8~VGK=E*_8wVEWalMd@2qqt+1WlzFVj4j@BtPMTzj*fO6J zzN`RWFD)a$Z~uP+{Mh9L1Qm6ufOK5>a+g*m9bc}1e%z8T-j{^m3dafD!MOR^r0f>v z8*ss)Cc^2pVh +#include + +#include +#include + +#include +#include + +typedef enum { + DemoEventTypeTick, + DemoEventTypeKey, + // You can add additional events here. +} DemoEventType; + +typedef struct { + DemoEventType type; // The reason for this event. + InputEvent input; // This data is specific to keypress data. + // You can add additional data that is helpful for your events. +} DemoEvent; + +typedef struct { + FuriString* buffer; + // You can add additional state here. + int counter; + bool pin_grounded; +} DemoData; + +typedef struct { + FuriMessageQueue* queue; // Message queue (DemoEvent items to process). + FuriMutex* mutex; // Used to provide thread safe access to data. + DemoData* data; // Data accessed by multiple threads (acquire the mutex before accessing!) +} DemoContext; + +GpioPin demo_message_pin; // This is the pin used for our GPIO demo. + +// Invoked when input (button press) is detected. We queue a message and then return to the caller. +static void gpio_polling_demo_input_callback(InputEvent* input_event, FuriMessageQueue* queue) { + furi_assert(queue); + DemoEvent event = {.type = DemoEventTypeKey, .input = *input_event}; + furi_message_queue_put(queue, &event, FuriWaitForever); +} + +// Invoked by the timer on every tick. We queue a message and then return to the caller. +static void gpio_polling_demo_tick(void* ctx) { + furi_assert(ctx); + FuriMessageQueue* queue = ctx; + DemoEvent event = {.type = DemoEventTypeTick}; + // It's OK to loose this event if system overloaded (so we don't pass a wait value for 3rd parameter.) + furi_message_queue_put(queue, &event, 0); +} + +// Invoked by the draw callback to render the screen. We render our UI on the callback thread. +static void gpio_polling_demo_render_callback(Canvas* canvas, void* ctx) { + // Attempt to aquire context, so we can read the data. + DemoContext* demo_context = ctx; + if(furi_mutex_acquire(demo_context->mutex, 200) != FuriStatusOk) { + return; + } + + DemoData* data = demo_context->data; + bool show_hello = !data->pin_grounded; + int counter = data->counter; + bool even_counter = (counter & 1) == 0; // If the lowest bit is 0, then counter is even. + + // Other fonts are FontPrimary, FontSecondary, FontKeyboard, FontBigNumbers, + canvas_set_font(canvas, FontPrimary); + canvas_draw_str_aligned(canvas, 64, 31, AlignLeft, AlignCenter, (show_hello ? "HELLO" : "WORLD")); + + // Put the lowest 4 digits of counter value into the buffer, then concatenate the text "Even" or "Odd". + furi_string_printf(data->buffer, "%04u", (counter % 10000)); + furi_string_cat_printf(data->buffer, " %s", (even_counter) ? ("Even") : ("Odd")); + + canvas_set_font(canvas, FontSecondary); + canvas_draw_str_aligned(canvas, 64, 42, AlignCenter, AlignTop, furi_string_get_cstr(data->buffer)); + + // Release the context, so other threads can update the data. + furi_mutex_release(demo_context->mutex); + + // Make tones if the speaker is available. + if (furi_hal_speaker_acquire(1000)) { + float freq = 100.0f + (counter*4.0); + float volume = 1.0f; + furi_hal_speaker_start(freq, volume); + furi_delay_ms(100); + furi_hal_speaker_stop(); + furi_hal_speaker_release(); + } +} + +// Our main loop invokes this method after acquiring the mutex, so we can safely access the protected data. +// We increment a counter and update if the GPIO pin is grounded. +static void gpio_polling_demo_update_pin_status(void* ctx) { + DemoContext* demo_context = ctx; + DemoData* data = demo_context->data; + data->counter++; + + // read returns true for VCC and false for ground, so invert answer. + data->pin_grounded = !furi_hal_gpio_read(&demo_message_pin); +} + +int32_t gpio_polling_demo_app(void* p) { + UNUSED(p); + + // Configure our initial data. + DemoContext* demo_context = malloc(sizeof(DemoContext)); + demo_context->mutex = furi_mutex_alloc(FuriMutexTypeNormal); + demo_context->data = malloc(sizeof(DemoData)); + demo_context->data->buffer = furi_string_alloc(); + demo_context->data->counter = 0; + demo_context->data->pin_grounded = false; + + // For this demo we are using pin "gpio_ext_pa4" from \firmware\targets\f7\furi_hal\furi_hal_resources.c + demo_message_pin = gpio_ext_pa4; + furi_hal_gpio_init(&demo_message_pin, GpioModeInput, GpioPullUp, GpioSpeedVeryHigh); + + // Queue for events (tick or input) + demo_context->queue = furi_message_queue_alloc(8, sizeof(DemoEvent)); + + // Set ViewPort callbacks + ViewPort* view_port = view_port_alloc(); + view_port_draw_callback_set(view_port, gpio_polling_demo_render_callback, demo_context); + view_port_input_callback_set(view_port, gpio_polling_demo_input_callback, demo_context->queue); + + // Open GUI and register view_port + Gui* gui = furi_record_open(RECORD_GUI); + gui_add_view_port(gui, view_port, GuiLayerFullscreen); + + // Update the screen fairly frequently (every 250 milliseconds.) + FuriTimer* timer = furi_timer_alloc(gpio_polling_demo_tick, FuriTimerTypePeriodic, demo_context->queue); + furi_timer_start(timer, 250); + + // Main loop + DemoEvent event; + bool processing = true; + do { + if (furi_message_queue_get(demo_context->queue, &event, FuriWaitForever) == FuriStatusOk) { + switch (event.type) { + case DemoEventTypeKey: + // Short press of back button exits the program. + if(event.input.type == InputTypeShort && event.input.key == InputKeyBack) { + processing = false; + } + break; + case DemoEventTypeTick: + // Every timer tick we update the pin status. + furi_mutex_acquire(demo_context->mutex, FuriWaitForever); + gpio_polling_demo_update_pin_status(demo_context); + furi_mutex_release(demo_context->mutex); + break; + default: + break; + } + + // Send signal to update the screen (callback will get invoked at some point later.) + view_port_update(view_port); + } else { + // We had an issue getting message from the queue, so exit application. + processing = false; + } + } while (processing); + + // Make pin float on exit. + furi_hal_gpio_init(&demo_message_pin, GpioModeInput, GpioPullNo, GpioSpeedVeryHigh); + + // Free resources + furi_timer_free(timer); + view_port_enabled_set(view_port, false); + gui_remove_view_port(gui, view_port); + view_port_free(view_port); + furi_record_close(RECORD_GUI); + furi_message_queue_free(demo_context->queue); + furi_mutex_free(demo_context->mutex); + furi_string_free(demo_context->data->buffer); + free(demo_context->data); + free(demo_context); + + return 0; +} \ No newline at end of file