Aether-Gateway

Automated Gateway install and configuration with Ansible.

Requirements/Dependencies

Ansible

sudo pacman -S ansible

Ansible Modules

ansible-galaxy collection install community.general

AWS CLI

sudo pacman -S aws-cli-v2-bin

If not done so, configure the AWS CLI:

aws configure

In the case of this project, the region is "us-east-1".

The user you wish to use for deploying the gateway and credentials should have adaquate permissions. See the IoT Core developer guide or workshop for more details. To use an account other than 'default', set the AWS_PROFILE environment variable to the name of the acount you want to use.

export AWS_PROFILE=user1

Next, if the account doesn't have an IAM role to manage IoT Core credentials (IoTWirelessGatewayCertManagerRole), follow these instructions.

Bootstrapping Your Account

In order to register devices with AWS, you need to bootstrap your account. Run the script:

./scripts/aws-bootstrap.sh

Creating the Installation Media

The script mksd.sh is responsible for automatically creating the Arch Linux ARM bootable SD card for the Raspberry Pi 3.

sudo ./mksd.sh <device>

Where <device> is the file path to the unmounted SD card (eg. /dev/sdc). The default login and password is "alarm".

The default root password is "root". After running ansible, SSH keys will be generated to facilitate logging in and the passwords will be randomized and uploaded to your AWS account's secret manager.

Installing Basic Station and Config via Ansible

If no errors were generated from creating the installation media, then the SD card is safe to be removed. Insert it in the Raspberry Pi and connect it through ethernet to a local network. First, get your local IP of the interface you're using to connect to the Pi:

ip a

You'll see an output similar to this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: eno1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default ql
en 1000
    link/ether 18:c0:4d:66:01:f8 brd ff:ff:ff:ff:ff:ff
    altname enp6s0
    inet 192.168.0.230/24 brd 192.168.0.255 scope global dynamic noprefixroute eno1
       valid_lft 5278sec preferred_lft 5278sec
    inet6 fe80::76e2:372:f1e3:f9aa/64 scope link noprefixroute
       valid_lft forever preferred_lft forever
3: wlp7s0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group defau
lt qlen 1000
    link/ether 86:3c:fa:b1:74:26 brd ff:ff:ff:ff:ff:ff permaddr a8:7e:ea:ca:e2:39

In my case, I'm using ethernet as well. Get the IP (including the /**) inet 192.168.0.230/24. Then, run:

sudo nmap -sn <ip>

Where ip is your IP. In my case, it's 192.168.0.230/24.

This will generate a report similar to this:

Starting Nmap 7.92 ( https://nmap.org ) at 2022-01-12 18:42 EST
Nmap scan report for 192.168.0.1
Host is up (0.00045s latency).
MAC Address: 6C:5A:B0:8E:22:20 (TP-Link Limited)
Nmap scan report for 192.168.0.53
Host is up (0.0012s latency).
MAC Address: B8:27:EB:2D:04:23 (Raspberry Pi Foundation)
Nmap scan report for 192.168.0.230
Host is up.
Nmap done: 256 IP addresses (3 hosts up) scanned in 1.95 seconds

Where you see (Raspberry Pi Foundation), copy the first IP above it. So 192.168.0.53.

Running Ansible

Now, all that's left is to run ansible. To install everything on the Pi, run:

ansible-playbook -u alarm --ask-pass -i <ip>, -K bootstrap.yml -e "gateway_name=<gwname>"

Where, <ip> is the Pi IP address and <gwname> is the name you want for the gateway. NOTE: it's important to have a comma , after the IP! When ansible-playbook runs, it'll ask you for the shell and root password. Those are the defaults previously mentioned (alarm and root).

Ansible Variable Options

The bootstrap playbook has some variables that can overridden, like the gateway name (although, that one is required). Below are the available variables. Add them to the -e argument in the ansible-playbook command, separated by a space.

• aws_register [truthy]: Select to register with AWS or not.
• gw_eui [string]: Override the gateway EUI. Assumes the gateway is already registered with AWS.

Deploying Gateway to another AWS Account

It's possible to redeploy the gateway to another AWS account without having to run ansible. To do this, you'll need to use the scripts/aws-register-gateway.sh script. You can set the AWS environment variables along with the environment variables needed for the script. Below is the example usage. If the gateway already exists, you should pass EXISTS=1 too. This will disassociate the AWS certificates and generate new ones for the gateway.

Required Environment Variables

• GATEWAY_EUI : The EUI of the gateway to deploy
• GATEWAY_NAME : The name of the gateway to deploy
• AWS_REGION : The AWS region to deploy to

GATEWAY_EUI=<gweui> GATEWAY_NAME=<name> AWS_REGION=<region> AWS_PROFILE=<profile> ./scripts/aws-register-gateway.sh

EXISTS=1 GATEWAY_EUI=<gweui> GATEWAY_NAME=<name> AWS_REGION=<region> AWS_PROFILE=<profile> ./scripts/aws-register-gateway.sh