Peripherals

Peripheral commands and variables enable access to general purpose input/outputs (GPIOs), analog functions such as analog-digital converters (ADCs) and PWMs (Pulse Width Modulators). In the case of the ACKme Numbat and Mackeral evaluation boards, peripherals include two user LEDs, two user buttons and the thermistor ADC.

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 pins differ depending on module and evaluation board. For a comparison of modules, see Module Comparison.

Wallaby Module and Mackerel Evaluation Board

The table below shows functions, defaults and pins for the AMW004 Wallaby GPIOs. The table also shows defaults, connections and header pins for the AMW004-E03.3 Mackerel evaluation board.

Wallaby AMW004Mackerel AMW004-E03.3
GPIODefaultADCPWMDACWakePinDefaultConnectionsHeader Pin
GPIO0pwm3dac07Standard I/O, factory resetButton 1H1-4
GPIO18system.indicator.gpio wlanLED G (Green)H1-3
GPIO29system.indicator.gpio networkLED Y (Yellow)H1-6
GPIO3adc4wake11noneH1-8
GPIO4adc512noneH1-7
GPIO5pwm0wake13system.indicator.gpio softapLED R (Red)H1-10
GPIO6pwm1wake14noneH1-9
GPIO7adc0pwm315noneThermistorH1-12
GPIO8adc117noneH1-11
GPIO9adc2pwm0wake18noneH1-14
GPIO10pwm3wake19noneH1-13
GPIO11pwm2wake20Standard I/O, wake,
web setup (see Web Setup Note)
Button 2H1-16
GPIO12adc3pwm1wake21noneH1-15
GPIO13uart1.rxadc623uart1.rxUART-2
GPIO14uart1.txadc724uart1.txUART-1
GPIO15uart1.rtspwm126uart1.rtsUART-3
GPIO16uart1.ctspwm227uart1.ctsUART-4
GPIO17spi0.clk
not available for digital I/O
wake30spi0.clkH2-13
GPIO18spi0.mosi
not available for digital I/O
31spi0.mosiH2-14
GPIO19spi0.miso
not available for digital I/O
32spi0.misoH2-11
GPIO20pwm0wake33H2-12
GPIO21adc8pwm034Standard I/OUser LED2H2-9
GPIO22adc935Standard I/OUser LED1H2-10
GPIO2336H2-7
GPIO24wake37H2-8
GPIO25uart0.tx38uart0.txH2-5
GPIO26uart0.rxwake39uart0.rxH2-6
GPIO27I2C_SCLwake41H2-3
GPIO28I2C_SDA42H2-4

Mackerel power header pins:

Numbat Module and Moray Evaluation Board

The table below shows functions, defaults and pins for the AMW006 / AMW106 Numbat GPIOs. The table also shows defaults, connections and header pins for the AMW006-E03.2 Moray evaluation board.

Numbat AMW006Moray AMW006-E03.2
GPIODefaultADCPWMWakePinDefaultAliasConnectionsHeader Pin
GPIO0spi1.mosi4Standard I/O, factory resetbutton_1Button 1H6-4
GPIO15none
GPIO2spi1.clk*6none
GPIO3spi1.cs*7none
GPIO4N/A8none
GPIO5spi1.mosi*pwm513system.indicator.gpio softapsoftap_ledLED R (Red)H8-13
GPIO6spi0.miso
not available for digital I/O
adc614spi0.misoH8-14
GPIO7spi0.clk
not available for digital I/O
adc515spi0.clkH8-15
GPIO8spi0.mosi
not available for digital I/O
adc716spi0.mosiH8-16
GPIO9uart0.rts17noneUART-3
GPIO10uart0.ctspwm018noneUART-4
GPIO11uart0.rxpwm019uart0.rxUART-2
GPIO12uart0.txpwm020uart0.txUART-1
GPIO13pwm121Standard I/Oled2User LED2H8-21
GPIO14I2C_SCLpwm322noneH8-22
GPIO15I2C_SDApwm323noneH8-23
GPIO16pwm624Standard I/Oled1User LED1H8-24
GPIO17uart1.rxadc3pwm425SPI CLKH8-25
GPIO1828system.indicator.gpio networknetwork_ledLED Y (Yellow)H7-28
GPIO19uart1.txadc2pwm429SPI MISOH7-29
GPIO20adc9pwm230noneThermistorH7-30
GPIO21adc8pwm231noneH7-31
GPIO22uart1.ctsadc0pwm1wake32Standard I/O, wake, web setupbutton2Button 2H7-32
GPIO23uart1.rtsadc1pwm433system.indicator.gpio wlanwlan_ledLED G (Green)H7-33

Moray power header pins:

Numbat Module and Marlin/Hopper Evaluation Board

The table below shows functions, defaults and pins for the AMW006 / AMW106 Numbat GPIOs. The table also shows defaults, connections and header pins for the AMW006-E03.2 Moray evaluation board.

Numbat AMW006Marlin/Hopper AMW006-E02.4/AMW006-A01.3
GPIODefaultADCPWMWakePinDefaultAliasConnections on MarlinMarlin Header Pin
GPIO0spi1.mosi4Standard I/O, factory resetbutton_1Button 1H5-13
GPIO15none
GPIO2spi1.clk*6noneH5-18
GPIO3spi1.cs*7noneH5-17
GPIO4N/A8none
GPIO5spi1.mosi*pwm513noneH5-11
GPIO6adc614spi0.misoSPI MISO
GPIO7adc515spi0.clkSPI CLK
GPIO8adc716spi0.mosiSPI MOSI
GPIO9uart0.rts17noneH5-16
GPIO10uart0.ctspwm018H5-12
GPIO11uart0.rxpwm019uart0.rxUART_RXH2-3
GPIO12uart0.txpwm020uart0.txUART_TXH2-2
GPIO13pwm121system.indicator.gpio networknetwork_ledLED Y (Yellow)
GPIO14I2C_SCLpwm322SPI_SCKH5-19
GPIO15I2C_SDApwm323SPI_CSH5-20
GPIO1624system.indicator.gpio softapsoftap_ledLED R (Red)
GPIO17adc3pwm425UART1_RXH2-8
GPIO1828system.indicator.gpio wlanwlan_ledLED G (Green)
GPIO19uart1.txadc2pwm429UART1_TXThermistorH2-9
GPIO20adc9pwm230noneH2-4
GPIO21adc8pwm231noneUser LED1H5-15
GPIO22uart1.ctsadc0pwm1wake32Standard I/O, wake, web setupbutton2Button 2H2-6
GPIO23uart1.rtsadc1pwm433User LED 2H2-7

Marlin power header pins:

Marlin reset header pin:

Viewing GPIO Usage

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

The default Mackerel GPIO usage is:

get  gp u
!  # Description
#  0 GPIO input_highz
#  1 system.indicator.wlan
#  2 system.indicator.network
#  5 system.indicator.softap
# 11 setup.control_gpio
# 13 UART1 RX
# 14 UART1 TX
# 17 SPI0 CLK
# 18 SPI0 MOSI
# 19 SPI0 MISO
# 21 GPIO output
# 22 GPIO output

The default Moray GPIO usage is:

> get gp u
!  # Description
#  0 GPIO input_highz (button1)
#  5 system.indicator.softap (softap_led)
#  6 SPI MISO
#  7 SPI CLK
#  8 SPI MOSI
# 11 UART0 RX
# 12 UART0 TX
# 13 GPIO output (led2)
# 16 GPIO output (led1)
# 18 system.indicator.network (network_led)
# 22 Standard I/O (button2)
# 23 system.indicator.wlan (wlan_led)

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

Note that the aliases shown in the Moray GPIO usage list above are set in the gpio_config_init.csv file provided with the Moray evaluation board. See Configuration and Setup, GPIO Configuration.

Setting GPIO Function

GPIO function can be set by commands or variables, or 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 WiConnect command if a gpio_config_init.csv file sets the GPIO function.

GPIOs that are already assigned to a function need to be deregistered before reassignment. If the GPIO is assigned to a system.indicator.gpio function, deregister or reassign the system.indicator.gpio function. See System Indicator Functions. Otherwise use the gpio_dir command with a none argument.

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:

set gpio.init <GPIO#> none
save

To use a GPIO as Standard I/O, 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.

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. 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 WiConnect 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 Wallaby Module and Mackerel Evaluation Board, Numbat Module and Moray Evaluation Board.

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.

To deregister a GPIO currently registered for a system indicator function, either disable the system indicator function or set it to another GPIO. For example, to deregister GPIO 1 on the Mackerel:

set sy i g wlan -1

Bus Stream Command GPIO

Set the bus.stream.cmd_gpio to configure a GPIO to force WiConnect 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).

WiConnect 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 WiConnect displays: Command Mode Start While holding down Button 2, WiConnect 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

WiConnect 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 UDP or TCP, with optional 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:

Network Status GPIO

The 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 asssignment of a GPIO to indicate whether a connected UDP client has data available to read.

Out-of-Band Interrupts

The system.oob variables allow a GPIO to be assigned for out-of-band (OOB) interrupts in response to specified events.

The OOB GPIO is asserted whenever one or more of the configured events occurs. It is de-asserted when reading the status register.

See in particular system.oob.gpio for details.

NOTE: The OOB gpio feature can be used by itself. The corresponding special function GPIO does not need to be enabled. For example, the network.status OOB event can be triggered without setting the network.status_gpio variable.

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.

goHACKme Solo GPIO

ghm.solo.gpio allows you to assign a GPIO to a goHACK.me stream or control parameter in solo mode.

Using a GPIO Alias

You can set a GPIO alias for any GPIO. The alias may be used instead of the GPIO number, since an alias is easier to remember. Using aliases can also help to make code more consistent and easier to read.

The default settings for the Moray board configure the alias led1 for GPIO13, so you can use the alias instead of the GPIO number: gdi led1 none

To create an alias for a GPIO, set the gpio.alias variable. For example, to set an alias for the Mackerel board user LED1: set gp a 22 led1

Now the same command works on both the Moray and Mackerel boards, even though GPIO assignments differ: gdi led1 none

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_direction) 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

ADCs

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 regardless of the GPIO function setting.

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 adc_max_value is 0xFFF (hex) = 4095 (dec).

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 Mackeral 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. A lookup table can also be specified when setting a GPIO for an ADC function using the ghm.solo.gpio variable.

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, or when the ghm.solo.gpio setting is specified. 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:

For evaluation boards with a thermistor, such as the Mackerel and Moray boards, a thermistor LUT is downloaded automatically to the module when you issue the ghm_capabilities download -s command in the course of a goHACK.me solo setup.

PWMs

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 with a PWM, a GPIO must be set to the none function with gpio_dir.

PWMs are associated with specific GPIOs. In the GPIO tables on this page (GPIO Functions and Pins), 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 module specific as shown in the tables below:

Wallaby PWMs

Number of independent PWMs (groups)4
minimum PWM frequency5Hz
Maximum frequency1.2MHz
PWM Group IDGPIOs
pwm05, 9, 20, 22
pwm16, 12, 15
pwm211, 16
pwm30, 7, 10

Numbat PWMs

Number of independent PWMs (groups)7
minimum PWM frequency1Hz
Maximum frequency21MHz
Numbat PWM Group IDGPIOs
pwm010, 11, 12
pwm113, 22
pwm220, 21
pwm314, 15
pwm417, 19, 23
pwm55
pwm616

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:

WiConnect 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)

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 no function is assigned to the GPIO. For example, to blink Moray user LED1, use the gpio_dir command and the pwm_update command:

WiConnect commandsComments

gdi 16 none
pwm 16 50 1

Deregister Moray User LED1 GPIO, in case it is assigned to a different function
Run the GPIO PWM at duty cycle 50%, frequency 1Hz

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 stop argument:

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:

WiConnect commandsComments

gdi 16 none
pwm 16 5 60

Deregister Moray User LED1 GPIO, in case it is assigned to a different function
Run the GPIO PWM at duty cycle 5%, frequency 60Hz

Communicating Peripheral Information Over the Network

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

WiConnect also provides general systems for handling information transfer.

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

The broadcast.udp.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.

The goHACK.me system provides a complete solution to remote monitoring and control of your ACKme device, including free web servers, a powerful and easy to use online interface, and a WiConnect API. See:

I2C Master Peripheral Controlling and Monitoring

For I2C_SCL and I2C_SDA signals, see:

For associated commands, see:

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:

For associated commands and variables, see:

Peripheral GPIO Mapping by Function

Wallaby GPIOs by Function

Wallaby UART

NameGPIO
uart0.tx25
uart0.rx26
uart0.ctsN/A
uart0.rtsN/A
uart1.tx14
uart1.rx13
uart1.cts16
uart1.rts15

Wallaby ADC

NameGPIO
adc07
adc18
adc29
adc312
adc43
adc54
adc613
adc714
adc821
adc922

Wallaby PWM

NameGPIOs
pwm05, 9, 20, 21
pwm16, 12, 15
pwm211, 16
pwm30, 7, 10

Wallaby SPI Master

NameGPIO
spi0.clk17
spi0.mosi18
spi0.miso19

Wallaby DAC

NameGPIO
dac00

Numbat GPIOs by Function

Numbat UART

NameGPIO
uart0.tx12
uart0.rx11
uart0.cts10
uart0.rts9
uart1.tx19
uart1.rx17
uart1.cts22
uart1.rts23

Numbat ADC

NameGPIO
adc022
adc123
adc219
adc317
adc4N/A
adc57
adc66
adc78
adc821
adc920

Numbat PWM

NameGPIOs
pwm010, 11, 12
pwm113, 22
pwm220, 21
pwm314, 15
pwm417, 19, 23
pwm55
pwm616

Numbat SPI Master

NameGPIO
spi0.clk7
spi0.mosi8
spi0.miso6

Numbat SPI Slave (Numbat v4+ Only)

NameGPIO
spi1.clk2
spi1.mosi5
spi1.miso0
spi1.cs3
spi1.irqoptional
spi1.rdyoptional