Multi-client WLAN Communications
This example demonstrates how to connect multiple Gecko OS devices running Gecko OS to a network as Wi-Fi clients, and how to configure each module to send messages to one another. The requirements for this kind of application can vary considerably, here's a list of assumptions we made for this particular example.
- Each Gecko OS device has a pre-assigned static IP address. This makes it easy for a device to send a message to another specific device on the network since all devices have pre-assigned addresses
- A message may be sent from one device to one or more devices
- There is no security encryption at the network layer, all modules can read messages from other devices if they choose to do so
- Message delivery is NOT guaranteed. If a message is sent from one device to one or more devices, and the message fails to be received, there are no retries at the network layer (retries at the Wi-Fi layer still work though).
The simplest way to enable devices to send messages to one another on a local network is to send messages in UDP broadcast packets. To receive messages, each device runs a UDP client and listens for messages sent on the UDP broadcast address. While UDP broadcast provides a way to send messages successfully, it lacks the ability to address messages to individual clients.
A Simple Message Protocol
To address messages, a simple application layer message protocol can be used. The requirements of a simple message protocol are listed below.
- Each message must have a sender (the source of the message)
- Each message must have one or more recipients (the destination of the message)
- Each message must have a payload
The message packet structure shown in the following diagram provides everything needed.
- Source Address : Source address of the device sending a message. A 1 byte address provides up to 128 unique addresses, and 128 multicast addresses as explained below.
- Destination Address : Destination address of the recipient of the message. If individual destination addresses are limited to 0 through 127, then addresses 128 through 255 can be used as multicast addresses. If the sender wants to send particular types of messages to a group of clients, the sender uses a multicast address. Devices interested in those types of messages can listen on the particular multicast address of interest, in addition to their own address
- Payload : The message payload
This example assumes each Wi-Fi device has a pre-allocated (or static) IP address. There are several ways to achieve this.
- Setup the DHCP server on your Wi-Fi access point to always allocate a particular IP address to each Wi-Fi device based on the MAC address of the device (the MAC address of your Gecko OS device is available by reading the wlan.mac variable.
- Ensure that each device that joins the Wi-Fi AP uses a static IP address, and that no two clients use the same IP address. You can set a static IP address for your device using the wlan.static.ip variable. Note that you will also need to set the wlan.static.netmask and wlan.static.gateway variables.
For this example, we assume that IP addresses assigned to clients are numbered in the range 192.168.1.100, 192.168.1.101, 192.168.1.102, and so on. We also assume the Wi-Fi AP (which is the network gateway) has an IP address of 192.168.1.1. The assumed configuration of the network is shown here.
Before continuing, ensure your Wi-Fi AP is configured as described above. Or alternately, if you have a different configuration, ensure you have the IP addresses and ranges of your AP handy (you will need to substitute them below as required).
Commands to setup the first device M0 at address 0 (192.168.1.100) are shown below. Enter these commands now.
|Gecko OS Commands for Module M0||Command Description|
With module M0 setup and ready, grab the next module (M1), plug it in and set it up using the same commands EXCEPT this time, change the
wlan.static.ip variable to
192.168.1.101 so module M1 has address 1.
Verify it works
With both modules setup and connected to the Wi-Fi AP and the UDP client started on both modules, let's test that messages sent from one module are received by the other module.
In the following Gecko OS session, the source and destination addresses (separated by commas) have been added to each message according to the simple message protocol described previously. Also, note that any text entered after a stream_write command is not echoed to the terminal.
Example Gecko OS Session
|Module 0||Module 1|
The stream_poll command is used here to check whether data has been received. A more convenient notification method is to setup a GPIO interrupt as described in the udp_client command.
Now you have two modules sending messages to each other, go ahead and add other modules to the network, remembering to increment the address for each new module.
This example describes a simple way to send messages between modules. There are other ways to achieve the same result, but the implementation of alternate methods is more complex.
- TCP client/server. Another option is to run a TCP server and TCP client on each module. Each time a module wants to send a message to another module, it must open a TCP client connection to the module it wishes to message. Each module must also run a separate TCP server to receive messages from other modules. This method provides guaranteed delivery, overcoming the potential for lost messages. Note that each module must solve the address problem described for UDP also.
Supporting Gecko OS Versions
- Gecko OS 4