GPIO-Controlled Network Connection

This example demonstrates how to use a GPIO to control a network connection to a remote server. Once the network connection is open, data can be automatically streamed between Gecko OS and the remote server.

Features Demonstrated


The Gecko OS ioconn feature makes it easy for an MCU, or blackbox electronic system with a serial output, to add network communication with a remote server. A GPIO is assigned as the ioconn.control_gpio. Toggling the ioconn control GPIO makes and breaks the network connection to the remote server.

The remote server used in the demonstration is the Zentri test TCP echo server, located online at The TCP echo server simply echoes any messages back to the client.

A computer, connected via USB to the evaluation board, takes the part of the MCU host system.

To set the level of the ioconn control GPIO high, various techniques are possible. In this demonstration, a switch is used to connect a logic high (3.3V) to the ioconn control GPIO pin. In an actual implementation, the host system toggles the ioconn control GPIO.

This demonstration uses the user LED GPIOs on the module for the ioconn control and status GPIOs. The LEDs are configured so that:

This demonstration works on a Gecko OS evaluation board.


Connect the switch between the IOC_CTRL and VDD_3V3. Sample pins are shown. Use the pins appropriate for your device and evaluation board:


| GPIO 22: Pin H2-10 | Pin H2-20| GPIO 21 |

Connect the module via USB to your computer and open a serial terminal console. See Getting Started.

The following assumes that the module is in the default state. To return to the default state, perform a factory reset.

Set up the local Wi-Fi network parameters.

Gecko OS commandsComments

set wlan.ssid <YOUR_SSID>
set wlan.passkey <YOUR_PASSKEY>
set wlan.auto_join.enabled 1

Set the wlan parameters for your local Wi-Fi access point
Remember to substitute correct values for your local Wi-Fi
Set up automatic network join

Set up aliases for the ioconn variables.

For example:

Gecko OS commandsComments

set gpio.alias 22 IOC_CTRL
set gpio.alias 21 IOC_STATUS

Set the alias 'IOC_CTRL' for GPIO22 (user LED1)
Set the alias 'IOC_STATUS' for GPIO21 (user LED2)

Configure the ioconn variables.

Gecko OS commandsComments

gdi IOC_CTRL none
set ioconn.control_gpio IOC_CTRL
set ioconn.enabled 1
set ioconn.local_port 5000
set ioconn.protocol tcp
set ioconn.remote_host
set ioconn.remote_port 50007
gdi IOC_STATUS none
set ioconn.status_gpio IOC_STATUS


Required if IOC_CTRL GPIO already in use
Set the GPIO to initiate connection
Enable GPIO-controlled connection
Specify local port
Specify protocol
Specify host to connect to
Specify port on host

Set the connection status GPIO

Reboot - changes are initiated at boot time

Performing a GPIO-Controlled Host Connection

When the IOC_CTRL GPIO is low, the stream_list command does not list any TCP client network stream:

> stream_list
! # Type  Info

Assert the module IOC_CTRL GPIO by setting the switch to ON.

If all goes well, the module terminal console displays something like the following:

Gecko OS Response

> Resolving host:
[2019-01-01 | 03:40:51: Opening:]
> Connecting (TCP):
[2019-01-01 | 03:40:52: Opened: 0]

The stream_list command lists the new TCP client network stream:

> stream_list
! # Type  Info
# 0 TCPC (22316)

While the IOC_CTRL GPIO is still asserted, send a message to the server:

Gecko OS commandsComments

write 0 16
hello IoT world!

Send message to stream 0 (server). Specify length of message
Enter the message on the next line
Gecko OS Response


Now check if a message has been received in reply:

Gecko OS commandsComments

read 0 1000

Read up to 1000 bytes from stream 0 (tcp test server)
Gecko OS Response

hello IoT world!

The server's response echoes the message sent.

De-assert the ioconn control GPIO by setting the switch to OFF.

The Gecko OS response is similar to the following:

Gecko OS Response

> [2019-01-01 | 03:42:13: Closed: 0]

Once again, the stream_list command does not list any TCP client network stream:

> stream_list
! # Type  Info

Using Stream Mode

A typical use of the GPIO Controlled Network Connection feature is to allow a device to stream data to and from a server. To demonstrate this, put the module in stream mode:

Gecko OS commandsComments

set bus.mode stream

Set the bus mode to stream
Reboot to bring up in stream bus mode.

The module terminal console can no longer send commands to Gecko OS. Try typing at the terminal. There is no response. Characters you type are transparently streamed to the network, which is currently not connected. See Serial Interface, Stream Mode.

Now assert the ioconn control GPIO by setting the switch to on.

Gecko OS responds as follows:

Gecko OS Response

> Resolving host:
[2019-01-01 | 03:40:51: Opening:]
> Connecting (TCP):
[2019-01-01 | 03:40:52: Opened: 0]

All characters received from the remote server appear automatically on the console.

Now type some characters into the module terminal console. Typed characters are echoed (after round-trip network latency) by the Zentri test server.

Supporting Gecko OS Versions

Change Log