[[PageOutline]] = OpenWrt GPIO = This page discusses aspects of GPIO particular to the OpenWrt BSP. For GPIO hardware and Linux basics please refer to the [wiki:gpio gpio] page. [=#gpiolib_sysfs] == Linux gpiolib / gpio class == The standard Linux way of working with GPIO's uses a gpio class accessed via {{{/sys/class/gpio/*}}} implemented through {{{gpiolib}}} (CONFIG_GPIOLIB, {{{drivers/gpio/gpiolib*}}}). For userspace access this requires sysfs kernel support (CONFIG_SYSFS) and the sysfs filesystem mounted which is standard for most linux systems including the Gateworks OpenWrt based BSP). This framework allows kernel board-support to define GPIO configuration (direction, direction-changeable, user-friendly name, state, and userspace configurable). The benefit of this standard method is: 1. its a linux standard 2. it allows you to configure GPIO's in such a way that users don't have the ability to change them to invalid states per hardware design 3. it allows you to name gpio's with a user-friendly name {{{#!comment For details on using the Linux gpio class from userspace see the [wiki:gpio#gpiolib gpio] page. }}} [=#init_script] == OpenWrt init script for configuring GPIO == If you wish to configure a GPIO differently from its power-on state, bootloader config state (if any), kernel config state (if any), you may do so in userspace. A common way to control board initialization is through init scripts. An example OpenWrt init-script that runs only at 'boot' time: * {{{/etc/init.d/gpio}}} {{{ #!bash #!/bin/sh /etc/rc.common # Copyright (C) 2006 OpenWrt.org START=20 boot() { [ -d /sys/class/gpio ] && { # Custom GPIO Configuration: # GW2382 - steer USB from FP to PCIe: echo 0 > /sys/class/gpio/gpio10/value } } }}} * to enable make sure this script is executable and enabled via: {{{ #!bash chmod +x /etc/init.d/gpio /etc/init.d/gpio enable }}} [=#button-hotplug-gw] == OpenWrt gpio-button-hotplug driver == OpenWrt uses a home-grown app called {{{procd}}} as PID1. One of {{{procd}}}'s features is to catch messages from the kernel and act upon them, much in the way a conventional linux system uses a hotplug helper and udev. The {{{/etc/hotplug.json}}} file configures how various events are handled: * using makedev to create device nodes in /dev on 'add' events and removing the nodes on 'remove' events * facilitate firmware loading * calling {{{/sbin/hotplug-call}}} on platform subsystem events * calling {{{/etc/rc.button/$BUTTON}}} on button (Linux input) events * calling {{{/sbin/hotplug-call}}} on various subsystem events (such as net, input, usb, block, atm, tty, button) Button (Linux input) events: - {{{/sbin/hotplug-call}}} will have the following defined: - {{{BUTTON}}} - button name (ie BTN_0 for user pushbutton) - {{{ACTION}}} - pressed|released - {{{SEQNUM}}} - a numeric value that increments with the event message - {{{SEEN}}} - number of seconds since last button event from driver * this can be used to determine how long a button has been 'held' for 'released' events. If a button is released and {{{SEEN=8}}} it has been held for 8 seconds The {{{gpio-button-hotplug}}} driver is the Linux kernel driver that creates hotplug events for GPIO based buttons. The {{{gpio-button-hotplug}}} out-of-tree driver is an OpenWrt custom driver that takes the place of the in-kernel {{{gpio-keys}}} (KEYBOARD_GPIO) and {{{gpio_keys_polled}}} (KEYBOARD_GPIO_POLLED) drivers and instead of emiting linux input events it emits uevent messages to the button subsystem which tie into the OpenWrt hotplug daemon. Note that for Ventana this uses the {{{gpio_keys}}} device-tree node to map gpio-240 to the {{{user_pb}}} button event. === Gateworks Button Hotplug package === The Gateworks [https://github.com/Gateworks/gw-openwrt-packages/tree/master/gateworks/button-hotplug-gw button-hotplug-gw] package installs the {{{/etc/hotplug.d/button/00-button}}} handler which does the following using UCI configuration for one or more buttons: * catching multiple successive button events (ie 3x press/release) * min and max hold times (ie catch a button release after being held for 10 secs) Example configuration ({{{/etc/config/system}}}): {{{ #!bash # catch BTN_0 pressed and released 3 times in quick succession (held for <1 sec each time): config button option button 'BTN_0' option action 'released' option handler 'logger BTN_0 pressed: 3x' option repeat '3' # catch BTN_0 released after behind held for 0 to 3 seconds config button option button 'BTN_0' option action 'released' option handler 'logger BTN_0 pressed: 0-3s' option min '0' option max '3' # catch BTN_0 released after behind held for 8 to 10 seconds config button option button 'BTN_0' option action 'released' option handler 'logger BTN_0 pressed: 8-10s' option min '5' option max '20' }}} * Note that the {{{logread}}} application can be used to read the output of the system log. By default {{{logger}}} will not send info to the serial console: {{{ #!bash logread -f # show all new log activity }}} Note that to use the user pushbutton present on the front panel of most Gateworks boards, you must configure the Gateworks System Controller (GSC) to not hard-reset the board on a button press: {{{ #!bash i2cset -f -y 0 0x20 0 0x00 # disable pushbutton hard reset i2cset -f -y 0 0x20 11 0xff # enable all interrupts }}} Refer to the [wiki:gsc#pushbutton GSC pushbutton] wiki section for information on properly configuring your board for pushbutton events and the [wiki:gsc#IRQ_GPIO_CHANGE GSC IRQ_GPIO_CHANGE] wiki section for information on GSC interrupts. ==== Factory Reset ==== In our latest [https://github.com/Gateworks/openwrt OpenWrt branch], we have added a factory reset handler through the above-mentioned button handler to factory reset the board. On first boot, the system uci entries default to the following: {{{ #!bash > uci show system ... system.@button[0]=button system.@button[0].button='BTN_0' system.@button[0].action='pressed' system.@button[0].handler='logger BTN_0 pressed' system.@button[1]=button system.@button[1].button='BTN_0' system.@button[1].action='released' system.@button[1].handler='factory_reset' system.@button[1].min='15' system.@button[1].max='999' ... }}} From the above, we can see that to invoke the factory reset, the pushbutton must be held for a minimum of 15s, to a maximum of 999s. This will invoke the function "factory_reset" which can be found in {{{/etc/hotplug.d/button/factory_reset}}}. The script will attempt to write to the console and log that a factory reset is occurring, as well as attempt to take over the user LEDs to make it a solid 'red' color. Change the {{{uci}}} entries to match your desired outcome. Please note that at the very least, both the IRQ_PB and IRQ_GPIO_CHANGE must be enabled in the gsc: {{{ #!bash i2cset -f -y 0 0x20 11 0x11 # enable IRQ_PB and IRQ_GPIO_CHANGE }}} [=#led] == GPIO based LEDs == GPIO's that drive LED's are controlled via the [wiki:gpio#led_class Linux led class]. OpenWrt has a UCI method of configuring LED's on boot via {{{/etc/config/system}}}. By default, the Gateworks OpenWrt BSP installs the '''userled-heartbeat'' package which sets the '''heartbeat''' trigger on the '''user1''' led. On most boards this is the green LED on the front-panel bi-color LED and results in the LED blinking green twice a second like a heartbeat. This is accomplished from the following configuration in {{{/etc/config/system}}}: {{{ #!bash config led option default '0' option name 'heartbeat' option sysfs 'user1' option trigger 'heartbeat' }}} See also: * [wiki:gpio#led_class Linux LED class]