Managing GPIOs and Peripherals
- GPIO Commands and Variables
- GPIO Functions and Pins
- Viewing GPIO Usage
- Deregistering a GPIO
- Setting GPIO Function
- Setting and Getting GPIO Values
- Communicating Peripheral Information Over the Network
- I2C Master Peripheral Controlling and Monitoring
- SPI Master Peripheral Controlling and Monitoring
- Peripheral GPIO Mapping by Function
Peripheral commands and variables enable access to general purpose input/outputs (GPIOs) and analog functions such as analog-digital converters (ADCs) and PWMs (Pulse Width Modulators).
In the case of the Zentri Numbat and Mackerel evaluation boards, peripherals include the thermistor ADC, two user LEDs, and two user buttons.
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):
- assigning a LED as wlan status indicator
- selecting between serial bus modes: COMMAND or STREAM
- pulse width modulator (PWM) function
- general standard IO function
- out-of-band interrupts
GPIO commands and variables allow control of the function and direction of the GPIOs.
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
For example, to deregister user LED1 on the Moray board (GPIO13):
gdi 13 none
You can also use the gpios_dir command, with an argument of
6, in the direction array position corresponding to the GPIO to be de-registered.
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
set ioconn.control_gpio -1
You can also deregister a GPIO by assigning its function to a different GPIO. For example, if ioconn.control_gpio is assigned to GPIO 6, you can deregister GPIO 6 by assigning the function to GPIO 7:
set ioconn.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.
GPIOS can also be set by a configuration file (see Configuration and Setup, GPIO Configuration).
If there is a
gpio_config_init.csv file present on the file system, this overrides any other GPIO settings at boot time. Some GPIO function changes are not implemented until reboot, and cannot be implemented by ZentriOS command if a
gpio_config_init.csv configuration file sets the GPIO function.
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
To use a GPIO with a PWM, use the pwm_update command. See PWMs.
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).
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:
- TCP with TLS
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.
GPIO Controlled Script
You can control the execution of a command script with a GPIO. See Configuration and Setup, Setup Configuration Script, and in particular Automatically Executing a Script - On GPIO Assertion or Reboot.
The associated variables are:
- setup.gpio.cmd - Set and get the command executed when setup.gpio.control_gpio asserted
- setup.gpio.control_gpio - Set and get the GPIO used for initiating a command or web setup sequence
- setup.gpio.level - Set and get the active logic level that indicates setup.gpio.control_gpio is asserted
- setup.gpio.mode - Set the execution mode for setup.gpio.cmd
Network Status GPIO
The wlan.network.status_gpio variable enables you to set and get the GPIO used to indicate network status.
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.
System Activity GPIO
The system.activity.gpio variables allows assignment of a GPIO to indicate specific types of system activity. Activity types are listed in the system.activity.gpio variable documentation.
The system.activity.gpio_level variables allows setting of the logic level corresponding to activity.
Bulk Flash GPIO
The system.bflash.cs_gpio variable allows adding bulk flash to the system.
System Wakeup GPIO
The system.wakeup.events variable allows assigning a GPIO to wake the module from sleep. Only GPIOs with
wake capability can be assigned to this function.
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
To read the value from an ADC, use the adc command. For example, to read the value for the Moray thermistor ADC (GPIO20):
> adc 20 0x7D7
The ADC value can be read only when the associated GPIO is deregistered and has no assigned system or Standard I/O function. See Deregistering a GPIO.
To convert the ADC_value to mV, use the following formula:
adc_mV = (Vref * adc_value) / adc_max_value
Vref is nominally 3300 (3.3V) and
0xFFF (hex) =
You can specify the ADC reference voltage with the system.adc.vref variable.
For example, using the nominal Vref the ADC value
0x7D7 converts to
1617 mV. This thermistor reading corresponds to a temperature of about 26 degrees Celsius when using the thermistor on the Mackerel or Moray evaluation board.
To determine temperature from the Mackerel and Moray thermistor ADC readings, see Temperature versus ADC value .
You can also send ADC values in broadcast UDP packets. See Broadcast UDP Packet.
ADC Lookup Tables
A LookUp Table (LUT) can be specified for an ADC using the
<LUT filename.csv> parameter with the adc_take_sample command.
The ADC is read and the raw value is used to find the two closest entries in the LUT. Those two entries are used to linearly interpolate the corresponding converted value of the ADC.
The LUT is parsed and loaded into RAM, either the first time a LUT file parameter is supplied with the adc_take_sample command. For every subsequent read of that ADC either with a lookup table specified, or with the
-l option, the cached LUT is used for the conversion. Only one LUT may be used for a given ADC. A reboot is required to load another LUT for the same ADC.
Care should be taken when generating the LUT as it is cached in the heap, i.e. the larger it is, the more RAM it takes away from other features.
Up to 3 ADC GPIOs may use a LUT.
The LUT is a CSV file with the following format:
<Raw ADC Value (0-4095)>,<Floating point number>\r\n
The table entries must follow these requirements:
- Must contain at least three entries
- Entries must be ordered with
<Raw ADC Value>in ascending order (i.e. the smallest ADC value is the first entry in the table, the largest ADC value is the last entry)
- The first entry MUST be the
<Raw ADC Value>of 0
- The last entry MUST be the
<Raw ADC Value>of 4095
Thermistors may vary. For precise temperature readings, create a LUT calibrated for your thermistor. See Temperature versus ADC value for a sample LUT.
PWMs (Pulse Width Modulators) can be used for blinking and dimming user LEDs. They can also be used for driving a speaker attached to a GPIO.
The pwm_update command provides control of the frequency and duty cycle of a PWM output.
Before using a GPIO with a PWM, ensure the GPIO is deregistered. See Deregistering a GPIO.
PWMs are associated with specific GPIOs. Each PWM has an associated group ID. Only one PWM GPIO in each group may be simultaneously and independently active.
The GPIO numbers, NOT the PWM ID numbers, are used in the pwm_update command.
PWM groups, maximum and minimum frequencies are device specific. See GPIO Functions and Pins and follow the link for your device. For Zentri devices, see:
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:
PWM control - Blinking and Dimming LEDs
You can use a PWM to blink an LED. A PWM can be used with a GPIO only when the GPIO is deregistered. See Deregistering a GPIO.
For example, to blink Moray user LED1, deregister the GPIO with the gpio_dir command and then set PWM values with the pwm_update command:
Using pwm_update on a GPIO assigns the corresponding PWM function to the GPIO. You can see this with the gpio_usage variable:
> get gp u ! # Description ... # 16 PWM6 (led1) ...
To turn off blinking, use the pwm_update command with the
pwm 16 stop
To dim the LED, reduce the duty cycle. To make blinking imperceptible, set the frequency to a rate above 30 Hz. For example, to dim the Moray user LED2:
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:
- TCP Client
- Multiple TCP Clients
- Secure TLS Client
- GPIO-Controlled Network Connection
- TCP Server + SoftAP
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.
I2C Master Peripheral Controlling and Monitoring
For I2C_SCL and I2C_SDA signals, see:
For associated commands, see:
- i2c_master_config - configure an I2C slave peripheral such as an accelerometer, humidity sensor, light sensor, etc.
- i2c_master_open - open an I2C stream for read/write
SPI Master Peripheral Controlling and Monitoring
Note: the GPIOs associated with SPI master signals are not available for digital I/O. See Wallaby SPI master, Numbat SPI master.
For SPI signals, see:
- AMW004 Wallaby GPIOs and pins - spio0 GPIOs are SPI Master
- AMW006/AMW106 Numbat GPIOs and pins - spio0 GPIOs are SPI Master
For associated commands and variables, see:
- spi_master_config - configure a SPI slave peripheral such as an accelerometer, humidity sensor, light sensor, etc.
- spi_master_open - open a SPI stream for read/write
- spi.master.active_gpio - GPIO asserted when SPI master bus accessed
- spi.master.active_level - asserted level for spi.master.active_gpio