Improve this doc
Network Setup on

Networking on resinOS 2.0

Introduction

In resinOS 2.0 the connectivity management has been change from ConnMan to NetworkManager. NetworkManager allows resinOS more flexibility when configuring the network setup and in conjunction with ModemManager allows resinOS to offer first class GSM/Cellular support.

All of the network configuration for resinOS can be done though files in the boot partition of your device. If you have a freshly downloaded resinOS .img you can mount it and inspect the resin-boot or resin-flash (for devices that boot from eMMC) partition. In the boot partition you will find a directory called system-connections.

The system-connections directory consists of a set of "connection files" one file per connection. If you added a wifi connection at from the dashboard when you downloaded your image, you should see two connection files resin-wifi and resin-sample. Both of these files are define a wifi connection type, but resin-sample is just a template or example file which you can copy to create new connections. You will notice that there is no file for ethernet, this is because NetworkManager will always set up a default ethernet connection. Most of the allowed options for these connection files can be found in the NetworkManager settings reference

Wifi Setup

If you entered your wifi SSID and passphrase when you downloaded resinOS from the dashboard you should have a file called resin-wifi in the image at /resin-boot/system-connections/.

[connection]
id=resin-wifi
type=wifi

[wifi]
hidden=true
mode=infrastructure
ssid=My Awesome Wifi Ssid

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

[wifi-security]
auth-alg=open
key-mgmt=wpa-psk
psk=super_secret_wifi_password

This file sets up a simple wifi connection to a network named My Awesome Wifi Ssid with a wifi password (psk) of super_secret_wifi_password. If you want to add multiple different wifi credentials, then simply make a copy of resin-wifi or resin-sample and change the SSID and psk key values. You can also add the autoconnect-priority integer values in each file to define the priority of each connection when the device has multiple wifi connections it can connect to.

The connection file also defines what kind of security the network expects, if you want to setup a network with a more elaborate security requirements, checkout the NetworkManager settings reference page.

As an example the below config sets up a WPA2-enterprise wifi connection:

[connection]
id=resin-wifi
type=wifi

[wifi]
ssid=PLACE_SSID_HERE
mode=infrastructure
security=802-11-wireless-security

[wifi-security]
key-mgmt=wpa-eap

[802-1x]
eap=peap
identity=PLACE_YOUR_ID_HERE
phase2-auth=mschapv2
password=PLACE_YOUR_PASSWORD_HERE

[ipv4]
method=auto

[ipv6]
method=auto

Regulatory Domain

By default, the wifi regulatory domain for your device is not set until it is connected to a network. If you need your device to connect at first boot to channels that may be restricted in some countries, you can specify the regulatory domain in the config.json file (like the above wifi settings, this is found in the boot partition). Regulatory domain is set using the country field.

As an example, if you are deploying your device in Great Britain and need it to connect to channel 12 or 13, you would set "country":"GB".

Setting a Static IP

Setting a static IP is possible by adding a few fields to the [ipv4] section of your connection file.

[connection]
id=my-ethernet
type=ethernet
interface-name=eth0
permissions=
secondaries=

[ethernet]
mac-address-blacklist=

[ipv4]
address1=192.168.1.111/24,192.168.1.1
dns=8.8.8.8;8.8.4.4;
dns-search=
method=manual

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
method=auto

The important bits to take note of here are interface-name=eth0 which indicates which network interface to use and the address1=192.168.1.111/24,192.168.1.1 line which shows we have a static IP of 192.168.1.111 and the network gateway is 192.168.1.1. The final piece is to add the dns=8.8.8.8;8.8.4.4; line, which tell the device to use Google DNS. The set up for a wifi connection is very much the same, as can be seen in the below example.

[connection]
id=resin-wifi
type=wifi

[wifi]
hidden=true
mode=infrastructure
ssid=PLACE_SSID_HERE

[ipv4]
address1=192.168.1.127/24,192.168.1.1
dns=8.8.8.8;8.8.4.4;
dns-search=
method=manual

[ipv6]
addr-gen-mode=stable-privacy
method=auto

[wifi-security]
auth-alg=open
key-mgmt=wpa-psk
psk=PLACE_YOUR_PASSWORD_HERE

Cellular Modem Setup

For cellular or GSM based connections, resinOS makes use of ModemManager and is configured in much the same way as wifi connections are configured. Currently, it is only possible to add a cellular configuration by adding a connection file to /resin-boot/system-connections in the downloaded OS .img file, but in the future cellular connections will be configurable from the dashboard at download time.

To set up a cellular connection with your device, just drop the below example configuration into a file in the /resin-boot/system-connections/ directory in the .img or on SD card (if you have it flashed with the OS already) and name it something like cellular. Replace the apn= and number= values with your mobile providers APN and PPP dialing number. If your mobile carrier requires a password and username, you will need to add those as well. For a more in depth look at available settings options for GSM, have a look at Table 91. gsm setting in the NetworkManager settings reference.

[connection]
id=resin-cellular
type=gsm
autoconnect=true

[gsm]
apn=giffgaff.com
number=*99#
password=password
username=giffgaff

[serial]
baud=115200

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Known Tested Modems:

At the time of writing we have tested a number of GSM modems with resinOS 2.0, in general most of the modems listed in the ModemManager Supported Devices list should work out of the box with resin.io, but below is a list of ones that have been tested and known to work.

  • Sierra Wireless MC8781 (USB AT command)
  • Huawei E3531 (USB AT command)
  • Huawei E1750 (USB AT command)
  • ONDA MT191UP (USB AT command)
  • Huawei E8231s-2 (USB Ethernet emulation)
  • Huawei E3531i-2 (USB Ethernet emulation)
  • Huawei E3131 (USB Ethernet emulation)
  • Fona 3G (USB AT command)
  • uBlox lisa-u200 (USB AT command)
  • Huawei ME909u-521 PCI-e
  • Huawei E3533
  • Huawei E398-u1 (cdc-wdm0) --> This device took a while to connect, most likely because it had to run usb_modeswitch first to put it into modem mode.

Note: If your are powering your USB modem from a Raspberry Pi, it is a good idea to enable the full 1.2A current throughput for the USB ports, you can see how to do this here

With some of the modems listed in the ModemManager Supported Devices list you may find they struggle to connect, this is most likely due to usb_modeswitch not knowing how to automatically switch the device to modem mode. In these cases you will need to have a look at your modem's data sheet and figure out how to force it to stay in modem mode.

Changing the Network at Runtime

Often there are times where the wifi network that the device will be provisioned into is not known before hand. In these cases the device needs a mechanism to be able to add its own wifi credentials during some kind of setup stage. For this reason we built the resin wifi connect project.

Resin wifi connect enables the device to create a wireless access point called ResinAP (also customisable) which serves a captive portal. This allows your end user to connect to the device and add their wifi credentials. The device will then automatically leave the setup mode and connect to the specified user network.

Under the hood resin wifi connect is interacting with NetworkManager via its DBUS API. The DBUS API is a useful way to interact with the resinOS host NetworkManager and there are DBUS bindings for most languages. Below is minimal python example from the NetworkManager examples.

Note: You will need to install the dbus module in order to run this example. i.e.: apt-get install python-dbus and make sure DBUS_SYSTEM_BUS_ADDRESS=unix:path=/host/run/dbus/system_bus_socket is exported in the environment, this is an important step as it ensures that DBUS calls are directed to the system bus that the resin HostOS is listening on rather than the DBUS bus in your container.

#!/usr/bin/env python
import dbus, uuid

s_con = dbus.Dictionary({
    'type': '802-11-wireless',
    'uuid': str(uuid.uuid4()),
    'id': 'My-WPA-PSK'})

s_wifi = dbus.Dictionary({
    'ssid': dbus.ByteArray("best-wifi"),
    'mode': 'infrastructure',
})

s_wsec = dbus.Dictionary({
    'key-mgmt': 'wpa-psk',
    'auth-alg': 'open',
    'psk': 'super-secret-password',
})

s_ip4 = dbus.Dictionary({'method': 'auto'})
s_ip6 = dbus.Dictionary({'method': 'ignore'})

con = dbus.Dictionary({
    'connection': s_con,
    '802-11-wireless': s_wifi,
    '802-11-wireless-security': s_wsec,
    'ipv4': s_ip4,
    'ipv6': s_ip6
     })


bus = dbus.SystemBus()

proxy = bus.get_object("org.freedesktop.NetworkManager", "/org/freedesktop/NetworkManager/Settings")
settings = dbus.Interface(proxy, "org.freedesktop.NetworkManager.Settings")

settings.AddConnection(con)

The above example will add a new wifi connection file to your hostOS NetworkManager configuration in /etc/NetworkManager/system-connections. It should be noted that you will not see a new file created in resin-boot/system-connections because there isn't a two way binding. The way it works is that on device boot, the files in resin-boot/system-connections is copied into /mnt/state/root-overlay/etc/NetworkManager/system-connections without removing any files from the destination. That directory is then bind mounted to /etc/NetworkManager/system-connections in the root filesystem on the Host.

Warning: It can be pretty dangerous if you install NetworkManager or python-networkmanager in your container, especially if you have INITSYSTEM=on, since systemd will automatically try to start your container NetworkManager and this will take your devices offline. It's very important to remember that making changes to the networking of a device is extremely dangerous and can lead to a device being unrecoverable, so exercise caution with any of the above.

Network Requirements

In order for a resin.io device to get outside of the local network and connect to the resin.io API, there are a few core network requirements.

Resin.io makes use of the following ports:

  • 443 TCP - This is the most fundamental requirement - it is used to connect to the VPN and the web terminal, and many web endpoints using TLS (https://.)
  • 123 UDP - For NTP time synchronisation.
  • 53 UDP - For DNS name resolution.

Each of these should work with outward only (and inward once outward connection established) firewall settings.

Additionally, if the network your device is connecting to works with whitelisting, you should whitelist the following domains on Port 80 and 443:

  • *.resin.io
  • *.pubnub.com

Additionally make an outgoing connection to mixpanel.com, but this is not a functional requirement for resin.io, but rather allows us to track some useful metrics.