Managing GPIOs and Peripherals

Peripheral commands and variables enable access to general purpose input/outputs (GPIOs).

GPIO Commands and Variables

Typically, particular GPIOs are hard-wired to components such as LEDs, buttons and sensors. Other GPIOs are configurable for input and output.

GPIOs can be used for special system functions, including (but not limited to):

GPIO commands and variables allow control of the function and direction of the GPIOs.

GPIO Commands

GPIO Variables

GPIO Functions and Pins

GPIO functions and pins differ for different devices. For a comparison of Zentri modules, see Module Comparison.

For details of particular devices, see Hardware.

Viewing GPIO Usage

To see the current GPIO usage, read the gpio.usage variable:

get gp u

For examples of gpio_usage output, see the module pages in Hardware.

The gpio_usage command does not list GPIOs set to none: these GPIOs have no function configured.

Deregistering a GPIO

GPIOs that are already assigned to a function need to be deregistered before reassignment. To determine if the GPIO is assigned, read the gpio.usage variable.

Deregistering a Standard I/O GPIO

If a GPIO is assigned to a Standard I/O function, use the gpio_dir command with an argument of none or -1.

For example, to deregister user LED1 on the Moray board (GPIO13):

gdi 13 none

For the change to persist after reboot, you need to set the gpio.init variable and save. For example:

set gpio.init 13 none
save

Deregistering Alternative Function GPIOs

Variables that allow functions to be assigned to a GPIO are as follows:

To de-register a GPIO assigned to a function, set the function variable to -1. For example, if the GPIO is assigned to setup.gpio.control_gpio:

set setup.gpio.control_gpio -1

You can also deregister a GPIO by assigning its function to a different GPIO. For example, if setup.gpio.control_gpio is assigned to GPIO 6, you can deregister GPIO 6 by assigning the function to GPIO 7:

set setup.gpio.control_gpio 7

If the GPIO is assigned to a system.indicator.gpio function, you need to specify the function argument as well as the GPIO number argument. See System Indicator Functions.

For example, to deregister GPIO 1 on the Mackerel, which is by default assigned to system.indicator.gpio wlan:

set sy i g wlan -1

Setting GPIO Function

GPIO function can be set by commands or variables.

To use a GPIO as Standard I/O, deregister the GPIO if it is already assigned, then use the gpio_dir command to set its direction.

For example, to set user LED1 on the Moray to an output:

gdi 13 out

For the change to persist after reboot, you need to set the gpio.init variable and save. For example:

set gpio.init 13 out
save

You can also use a GPIO for a number of special functions, such as indicators, or inputs to control special features.

System Indicator Functions

Use the system.indicator.gpio and system.indicator.state to configure a GPIO for a system indicator function. Deregister the GPIO if necessary before setting its function.

Save the variables and reboot to complete the configuration change, since these functions are managed by services configured during bootup.

Note: This GPIO function change cannot be implemented by ZentriOS command if a gpio_config_init.csv file sets the GPIO function.

On the Mackerel and Moray evaluation boards, the red, yellow and green LEDs are configured by default as system indicators, showing soft AP, network and wlan status. See:

For example, to switch the network system indicator function to Mackerel user LED 1 (GPIO 22):

gdi 22 none
set sy i g network 22
save
reboot

Each system indicator function can be associated with only one GPIO. Setting the indicator to a GPIO automatically sets to none ( any GPIO previously assigned to that system indicator.

Bus Stream Command GPIO

Set the bus.stream.cmd_gpio to configure a GPIO to force ZentriOS from stream mode to command mode. See Serial Interface for a discussion of stream mode and command mode.

This feature is intended for automated use with a host MCU. In the following demonstration of this feature on the Mackerel evaluation board, we use Button 2 (GPIO 11).

ZentriOS commandsComments

gdi 11 none
set bu s g 11
set bu m stream
save
reboot


Deregister Mackerel Button 2 GPIO
Configure Button 2 GPIO as bus.stream.cmd_gpio
Set the bus mode to stream
Save variables
The changed bus mode is not implemented until boot

Because the device is in stream mode, characters typed into the serial terminal are not echoed. Press Button 2, and ZentriOS displays: Command Mode Start While holding down Button 2, ZentriOS commands may be typed into the terminal, and characters are echoed. For example, you can set bus mode to command and save, to restore command mode after a reboot. Release Button 2 and the device returns to stream mode.

GPIO Controlled Network Connection

ZentriOS allows you to configure full details of a connection to a host, then connect and disconnect under the control of a single GPIO. The connection can be via:

Set ioconn.control_gpio to assign a GPIO to the control function that makes and breaks the connection.

Set ioconn.status_gpio to assign a GPIO to indicate the status of the connection.

See the ioconn.* variables for details.

The GPIO-Controlled Network Connection application note provides further examples.

TCP Server Status GPIOs

The tcp.server.connected_gpio variable provides a GPIO to indicate whether a client is connected to the TCP server.

The tcp.server.data_gpio variable provides a GPIO to indicate whether a connected client has data available to read.

See the TCP Server + softAP application note for further information.

UDP Server Data GPIO

The udp.server.data_gpio variable allows assignment of a GPIO to indicate whether a connected UDP client has data available to read.

Setting and Getting GPIO Values

If a GPIO is set to the Standard I/O function, and the GPIO direction is set as an output with the gdi (gpio_dir) command, the GPIO value may be configured with the gse (gpio_set) and gge (gpio_get) commands. For example:

> gdi 12 out
Set OK
> gge 12
0
> gse 12 1
Set OK
> gge 12
1

If a Standard I/O GPIO is configured for input, you can read the GPIO value but you cannot set it:

> gdi 12 in
Set OK
> gge 12
0
> gse 12 1
GPIO not configured for output
Command failed

LEDs

The level of a LED can be controlled via a GPIO, either with the Standard I/O output or by using a PWM.

GPIO Standard I/O Control

A LED can be turned on or off by configuring as a Standard I/O output, then setting the GPIO level.

For example, to turn on Mackerel user LED1, use the gpio_dir command and the gpio_set command:

ZentriOS commandsComments

gdi 22 none
gdi 22 out
gse 22 1
gse 22 0


Deregister Mackerel User LED1 GPIO, in case it is assigned to a different function
Assign User LED1 GPIO to a Standard I/O output
Set GPIO output high (LED1 on)
Set GPIO output low (LED1 off)

Communicating Peripheral Information Over the Network

The ZentriOS TCP and UDP client and server features provide frameworks for building a customised application for transmitting and receiving monitor and control data from your ZentriOS device. For examples of these applications, see:

ZentriOS also provides general systems for handling information transfer.

A ZentriOS device can be configured to broadcast GPIO and ADC data at regular intervals, via the broadcast group of variables.

The broadcast.data variable lets you specify what data is broadcast. GPIOs are specified by GPIO number, and ADCs are specified by ADC number. See the Broadcast UDP Packet for a demonstration of this feature.

Peripheral GPIO Mapping by Function