Merge pull request #20782 from krzysztof-cabaj/example-LEDs

examples/leds_shell: add example for interactive LEDs/GPIO control

examples/leds_shell/Makefile

@@ -0,0 +1,22 @@
+# Set the name of your application:
+APPLICATION = leds_shell
+
+# 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)/../../
+
+# Uncomment this to enable 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 to show compiler invocation lines by default:
+QUIET ?= 1
+
+# Modules to include:
+USEMODULE += shell
+USEMODULE += periph_gpio
+
+include $(RIOTBASE)/Makefile.include

examples/leds_shell/Makefile.ci

@@ -0,0 +1,3 @@
+BOARD_INSUFFICIENT_MEMORY := \
+    atmega8 \
+    #

examples/leds_shell/README.md

@@ -0,0 +1,81 @@
+# LEDs and basic GPIO example application
+
+## Description
+
+The application `leds_shell` is a basic example, which allows easy, interactive
+control of internal board LEDs, and basic GPIO for externally connected simple
+devices (for e.g. additional LEDs, relay, motors - via dedicated drivers, etc.)
+via the shell.
+
+In particular, this example shows:
+- on/off and toggle internal board LEDs.
+- initialize GPIO port in output mode.
+- set GPIO port state to HIGH or LOW.
+
+## Shell command
+
+The following commands are available:
+
+- `led`: allows switching on/off or toggle internal board LEDs.
+- `gpio`: allows initialization of GPIO port and set state to HIGH/LOW.
+- `help`: default RIOT command, which shows available commands.
+
+## Usage on `BOARD=native`
+
+- Build and run `leds_shell` example application on the `native` target,
+as Linux application:
+
+```
+$ make all term
+[...]
+RIOT native interrupts/signals initialized.
+RIOT native board initialized.
+RIOT native hardware initialization complete.
+
+main(): This is RIOT! (Version: 2021.07-devel-10893-gb2e97-example-leds_shell)
+This board has 2 LEDs
+>
+```
+
+- List the available commands:
+```
+> help
+help
+Command              Description
+---------------------------------------
+gpio                 GPIO pin initialization and set port state HIGH/LOW
+led                  Switch on/off or toggle on-board LEDs
+```
+
+- Enable internal LED0 and LED1 (the `native` target has two virtual LEDs):
+
+```
+> led 0 on
+led 0 on
+LED_RED_ON
+
+> led 1 on
+led 1 on
+LED_GREEN_ON
+```
+## Usage on actual hardware - `BOARD=stm32f469i-disco`
+
+- Build and flash `leds_shell` example application on sample board, for example
+ `stm32f469i-disco` target, which has 4 internal LEDs:
+
+```
+$ make all BOARD=stm32f469i-disco flash term
+[...]
+main(): This is RIOT! (Version: 2021.07-devel-10894-g2ad22b9-example-leds_shell)
+This board has 4 LEDs
+> help
+help
+Command              Description
+---------------------------------------
+gpio                 GPIO pin initialization and set port state HIGH/LOW
+led                  Switch on/off or toggle on-board LEDs
+```
+
+- Switch on/off internal LEDs using `led` command and appropriate LED id.
+- Initialize GPIO port using `gpio init`.
+- Change state of GPIO port using `gpio set` and `gpio clear`.

examples/leds_shell/main.c

@@ -0,0 +1,111 @@
+/*
+ * Copyright (C) 2024 Krzysztof Cabaj <kcabaj@gmail.com>
+ *
+ * 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       leds_shell - sample application for demonstrating internal
+ *              board LEDs on/off and basic GPIO using interactive RIOT shell
+ *
+ * @author      Krzysztof Cabaj <kcabaj@gmail.com>
+ *
+ * @}
+ */
+
+#include "stdio.h"
+#include "stdlib.h"
+#include "shell.h"
+#include "led.h"
+#include <periph/gpio.h>
+
+static int gpio_command(int argc, char **argv)
+{
+    if (argc < 4) {
+        printf("usage: %s <init/set/clear> <port no.> <pin no.>\n", argv[0]);
+        return -1;
+    }
+
+    int port_no = atoi(argv[2]);
+    int pin_no = atoi(argv[3]);
+
+    if (strcmp(argv[1], "init") == 0) {
+        printf("GPIO initialization PORT %d, PIN %d\n", port_no, pin_no);
+
+        int result;
+
+        result = gpio_init(GPIO_PIN(port_no, pin_no), GPIO_OUT);
+
+        if (result == 0) {
+            printf("Success!\n");
+        }
+        else {
+            printf("Failure!\n");
+        }
+    }
+    else if (strcmp(argv[1], "set") == 0) {
+         printf("Set HIGH to PORT %d, PIN %d\n", port_no, pin_no);
+         gpio_set(GPIO_PIN(port_no, pin_no));
+    }
+    else if (strcmp(argv[1], "clear") == 0) {
+         printf("Set LOW to PORT %d, PIN %d\n", port_no, pin_no);
+         gpio_clear(GPIO_PIN(port_no, pin_no));
+    }
+    else {
+        printf("usage: %s <init/set/clear> <port no.> <pin no.>\n", argv[0]);
+    }
+
+    return 0;
+}
+
+static int led_command(int argc, char **argv)
+{
+    if (argc < 3) {
+        printf("usage: %s <id> <on|off|toggle>\n", argv[0]);
+        return -1;
+    }
+
+    int led_id = atoi(argv[1]);
+
+    if (led_id >= LED_NUMOF) {
+        printf("This board has %d LEDs\n", LED_NUMOF);
+        return -1;
+    }
+
+    if (strcmp(argv[2], "on") == 0) {
+        led_on(led_id);
+    }
+    else if (strcmp(argv[2], "off") == 0) {
+        led_off(led_id);
+    }
+    else if (strcmp(argv[2], "toggle") == 0) {
+        led_toggle(led_id);
+    }
+    else {
+        printf("usage: %s <id> <on|off|toggle>\n", argv[0]);
+    }
+
+    return 0;
+}
+
+static const shell_command_t commands[] = {
+    { "gpio", "GPIO pin initialization and set port state HIGH/LOW", gpio_command },
+    { "led", "Switch on/off or toggle on-board LEDs", led_command},
+    { NULL, NULL, NULL }
+};
+
+int main(void)
+{
+    char line_buf[SHELL_DEFAULT_BUFSIZE];
+    printf("This board has %d LEDs\n", LED_NUMOF);
+
+    shell_run(commands, line_buf, SHELL_DEFAULT_BUFSIZE);
+
+    return 0;
+}