LANcube Software installation

Creative Commons Attribution-ShareAlike 4.0 International License

Last update: September 11 2023

How to access the LAN3V2

From internet:

ssh -p 2022 sand@router_public_ip
[$[Get Code]]

or

inside a private network

ssh sand@servers_local_ip
[$[Get Code]]

From the internet, port 2022 is used instead of standard port 22 to reduce risk of attacks by hackers. A password and user name is required. The standard username is sand. The system administrator should be able to provide you the password for sand. On the local network, we typically reserve the IP 192.168.0.100 for the raspberry pi.

Installing and configuring subsystems

  • On a computer, download the Raspberry Pi imager here
  • install the OS on a microSD card by using the Raspberry Pi imager.
  • Connect the Raspberry pi to the internet via the ethernet interface, connect a keyboard and mouse along with a screen.
  • Install the UPS hat on the RPI
  • Put the microSD card on the RPI and power it on.
    • Set Country, time zone and language to whatever you want. We will anyway change it later on.
    • You will be asked to activate the wifi. You can set it up if you wish to use it.
    • The Raspberry will initiate a software update
    • Restart the computer when prompt for it.
  • Set time, time zone and date
    • time zone have to be GMT
    sudo dpkg-reconfigure tzdata
    [$[Get Code]]
    • Select None of the above
    • Select GMT
  • Create the sand account
sudo useradd sand
sudo passwd sand
sudo mkdir /home/sand
sudo cp /home/pi/.bashrc /home/sand/
sudo chown -R sand /home/sand
sudo chgrp -R sand /home/sand
sudo sh -c 'echo "sand ALL=(ALL:ALL) ALL" >> /etc/sudoers'
[$[Get Code]]
  • Edit /etc/passwd
sudo apt install vim
sudo vim /etc/passwd
[$[Get Code]]
  • Enter the input mode by typing < i > and add the following text at the end of the last line if it is not already there (N.B. < i > is the keyboard key i)
/bin/bash
[$[Get Code]]
  • Use the raspberry configuration tool to deactivate Auto login
sudo raspi-config
[$[Get Code]]
  • Select 1 System Options
  • Select S5 Boot / Auto Login
  • Select B3 Desktop GUI, requiring user to login
  • Select Finish
  • Accept to reboot the raspberry
  • Login as sand
  • Install the following packages
sudo apt-get update && sudo apt-get upgrade
sudo apt-get install vim
sudo apt-get install vim-common
sudo apt-get install apache2
sudo apt-get install openssh-client
sudo apt-get install openssh-server
sudo apt-get install git
sudo apt-get install python3-gpiozero
sudo apt-get install libatlas-base-dev
sudo pip3 install pandas
sudo pip3 install pyserial
sudo pip3 install pynmea2

[$[Get Code]]

Mount the usb stick on /home/sand/backup (Optional)

The usb stick will be the support to backup all the data. The backup will be done at 9 AM UT. That will be managed by the crontab.

  • Create the data backup directory
mkdir /home/sand/backup
[$[Get Code]]
  • Plug the usb stick in one of the RPI usb port. Type the following command:
sudo lsblk
[$[Get Code]]

You should see the usb drive on the sda1 drive

  • Edit fstab to mount the usb stick at /home/sand/backup
sudo umount /dev/sda1
sudo su
echo "/dev/sda1 /home/sand/backup vfat rw,user,exec,nofail,umask=000 0 0" >> /etc/fstab
exit
sudo reboot
[$[Get Code]]

Notes:

  • We assume that the file system on your usb stick is FAT. Please be sure to format the usb stick accordingly before the installation.
  • Be sure to replace /dev/sda1 with your actual device.

crontab

The crond daemon is scheduling repetitive tasks on linux systems. Users who have the right to use crond can schedule their own tasks to crond. Here we use the crontab system to backup the data to the backup directory on the usb stick. The files will be sinched every 15 min (00, 15, 30,45). There is also the script web-preview.bash that will start every minute. This script aim to create a page showing the latest recorded readings. The data is updated every 5 seconds.

  • Edit crontab
sudo su
crontab -e
[$[Get Code]]
  • chose editor 3. /usr/bin/vim.basic
  • type < i > and add the following content:
*/15 * * * * /usr/bin/rsync -a /var/www/html/data/* /home/sand/backup
*/1 * * * * bash /usr/local/bin/web-preview.bash
[$[Get Code]]
  • Save and quit by typing: <escape> :wq
exit
[$[Get Code]]

SSH

SSH server allows any remote SSH client to connect to the server to remotely control system programs from the command line or to download (upstream / downstream) data.

  • We must first be sure that the SSH server start automatically when the RPI boots.
sudo raspi-config
[$[Get Code]]
  • Select 3 Interfacing Options
    • SSH
      • Yes (to enable ssh)
  • ok
  • Finish
  • Set up your personal firewall to allow the SSH and http connections to pass through the firewall.
sudo iptables -I INPUT 1 -p tcp --dport 22 -j ACCEPT
sudo iptables -I INPUT 1 -p tcp --dport 80 -j ACCEPT
sudo iptables-save
[$[Get Code]]

Installing LAN3V2 applications

Latest available package release on github repository

  • To download LAN3V2 apps:
cd
mkdir git
cd git
git clone https://github.com/aubema/lancube.git
[$[Get Code]]
  • Copy apps to system directory:
sudo cp -f /home/sand/git/lancube/* /usr/local/bin/
sudo chmod a+rx /usr/local/bin/*
[$[Get Code]]

Apache server

We are using the Apache2 web server. This server allows browsing the database and look at the log file.

To activate the web server, we must:

  • activate userdir module
sudo a2enmod userdir
sudo service apache2 restart
[$[Get Code]]
  • Create the data directory and modify the permissions by doing:
sudo mkdir /var/www/html/data
sudo chmod a+rwx /var/www/html/data
[$[Get Code]]
  • Edit the apache2 configuration file
sudo vim /etc/apache2/apache2.conf
[$[Get Code]]
  • Then type < i > to enter insert mode and add the following lines to the file
# added for lan3v2
<Directory /var/www/html/data>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all granted
</Directory>
[$[Get Code]]
  • Then exit and save by typing: <escape> :wq
  • Restart the webserver
sudo a2enmod userdir
sudo service apache2 restart
[$[Get Code]]

Real time clock

We are using the DS3231 RTC module to keep the date and time after powering off the system. In LAN3V2, the RTC module is included with the UPS hat.

  • Update the RPI
sudo apt-get update
sudo apt-get upgrade
[$[Get Code]]

Configure the I2C interface

sudo raspi-config
[$[Get Code]]

This command will bring up the configuration tool; this tool is an easy way to make a variety of changes to your Raspberry Pi’s configuration. Today, however, we will only by exploring how to enable the I2C interface.

Use the arrow keys to go down and select “3 Interfacing Options“. Once this option has been selected, you can press Enter.

  1. On the next screen, you will want to use the arrow keys to select “P5 I2C“, press Enter once highlighted to choose this option.
  2. You will now be asked if you want to enable the “ARM I2C Interface“, select Yes with your arrow keys and press Enter to proceed.
  3. Once the raspi-config tool makes the needed changes, the following text should appear on the screen: “The ARM I2C interface is enabled“.
  • You can run the following command on your Raspberry Pi to detect that you have correctly wired up your RTC device.
sudo i2cdetect -y 1
[$[Get Code]]

If you have successfully wired up your RTC circuit, you should see the ID #68 appear. This id is the address of the DS3231 RTC Chips. Once we have the Kernel driver up and running the tool will start to display UU instead, this is an indication that it is working as intended.

Setting up the Raspberry Pi RTC Time

With I2C successfully setup and verified that we could see our RTC circuit then we can begin the process of configuring the Raspberry Pi to use our RTC Chip for its time.

  1. To do this, we will first have to modify the Raspberry Pi’s boot configuration file so that the correct Kernel driver for our RTC circuit will be successfully loaded in.
  • Run the following command on your Raspberry PI to begin editing the /boot/config.txt file.
sudo vim /boot/config.txt
[$[Get Code]]
  • Within this file, you will want to add the following line to the bottom of the file.
dtoverlay=i2c-rtc,ds3231
[$[Get Code]]

Once you have added the correct line for your device to the bottom of the file you can save and quit out of it by pressing Esc, then :wq and then Enter.

With that change made we need to restart the Raspberry Pi, so it loads in the latest configuration changes.

  • Run the following command on your Raspberry Pi to restart it.
sudo reboot
[$[Get Code]]
  • Once your Raspberry Pi has finished restarting we can now run the following command, this is so we can make sure that the kernel drivers for the RTC Chip are loaded in.
sudo i2cdetect -y 1
[$[Get Code]]

You should see a wall of text appear, if UU appears instead of 68 then we have successfully loaded in the Kernel driver for our RTC circuit.

Now that we have successfully got the kernel driver activated for the RTC Chip and we know it’s communicating with the Raspberry Pi, we need to remove the fake hwclock package. This package acts as a placeholder for the real hardware clock when you don’t have one.

  • Type the following two commands into the terminal on your Raspberry Pi to remove the fake-hwclock package. We also remove hwclock from any startup scripts as we will no longer need this.
sudo apt-get -y remove fake-hwclock
sudo update-rc.d -f fake-hwclock remove
[$[Get Code]]

Now that we have disabled the fake-hwclock package we can proceed with getting the original hardware clock script that is included in Raspbian up and running again by commenting out a section of code.

  • Run the following command to begin editing the original RTC script.
sudo vim /lib/udev/hwclock-set
[$[Get Code]]

If you upgrade the operating system, you may need to redo the following step.

  • Find and comment out the following three lines by placing # in front of it as we have done below.
    • Find
    if [ -e /run/systemd/system ] ; then
    exit 0
    fi
    [$[Get Code]]
    • Replace With
    #if [ -e /run/systemd/system ] ; then
    # exit 0
    #fi
    [$[Get Code]]
  • Once you have made the change, save the file by pressing Esc then :wq then Enter.

Syncing time from the Pi to the RTC module

Now that we have our RTC module all hooked up and Raspbian and the Raspberry Pi configured correctly we need to synchronize the time with our RTC Module. The reason for this is that the time provided by a new RTC module will be incorrect.

  • You can read the time directly from the RTC module by running the following command if you try it now you will notice it is currently way off our current real-time.
sudo hwclock -D -r
[$[Get Code]]
  • Now before we go ahead and sync the correct time from our Raspberry Pi to our RTC module, we need to run the following command to make sure the time on the Raspberry Pi is in fact correct. If the time is not right, make sure that you are connected to a Wi-Fi or Ethernet connection.
date
[$[Get Code]]
  • If the time displayed by the date command is correct, we can go ahead and run the following command on your Raspberry Pi. This command will write the time from the Raspberry Pi to the RTC Module. If the time displayed is wrong, skip to the next section (Syncing the Pi to the RTC on startup).
sudo hwclock -w
[$[Get Code]]
  • Now if you read the time directly from the RTC module again, you will notice that it has been changed to the same time as what your Raspberry Pi was set at. You should never have to rerun the previous command if you keep a battery in your RTC module.
sudo hwclock -r
[$[Get Code]]

Syncing the Pi to the RTC on startup

  • If we want the pi to sync with internet time on startup, we will need to enable ntp protocol. To do so, just write the following line in the terminal.
sudo timedatectl set-ntp 1
[$[Get Code]]
The activation of the ntp clock sync will not affect the RTC clock sync when the internet is unplugged.
  • If you want to set the date manually to the RTC clock, you can now do it by writing the following command (adapt the date and time to your situation):
sudo hwclock --set --date "8/11/2013 23:10:45"
sudo hwclock -s
[$[Get Code]]
You can make sure that it worked by typing:
date
[$[Get Code]]
  • Next, you will need to add the RTC device creation at boot by editing the /etc/rc.local file by running
sudo vim /etc/rc.local
[$[Get Code]]
and by adding the following line to the file just before the "exit 0":
sudo hwclock -s
[$[Get Code]]
Once you have made the change, save the file by pressing Esc then :wq then Enter.
  • We must restart the Raspberry Pi. To do this, type the following command into the terminal on your Raspberry Pi to restart it.
sudo reboot
[$[Get Code]]

Now, you should hopefully now have a fully operational RTC module that is actively keeping your Raspberry Pi’s time correct even when it loses power or loses an internet connection.

Light sensors

The light sensors use the same protocol as the RTC module. Therefore, in order to complete the installation correctly, please make sure you activated the I2C protocol as shown in the previous section.

In order to connect multiple sensors with the same address via I2C protocol on the raspberry pi, it is necessary to configure other I2C busses by changing GPIO ports as SDA and SCL pin.

  • To create additional I2C busses, run :
sudo vim /boot/config.txt
[$[Get Code]]
Once you have added the correct line for your device to the bottom of the file you can save and quit out of it by pressing Esc, then :wq and then Enter.
  • Add the following lines of code in the section where spi and i2c is enabled :
dtoverlay=i2c-gpio,bus=7,i2c_gpio_delay_us=1,i2c_gpio_sda=5,i2c_gpio_scl=6
dtoverlay=i2c-gpio,bus=6,i2c_gpio_delay_us=1,i2c_gpio_sda=13,i2c_gpio_scl=19
dtoverlay=i2c-gpio,bus=5,i2c_gpio_delay_us=1,i2c_gpio_sda=12,i2c_gpio_scl=16
dtoverlay=i2c-gpio,bus=4,i2c_gpio_delay_us=1,i2c_gpio_sda=23,i2c_gpio_scl=24
dtoverlay=i2c-gpio,bus=3,i2c_gpio_delay_us=1,i2c_gpio_sda=22,i2c_gpio_scl=25
[$[Get Code]]
Note that if you use the UPS hat recommended in this doc, the pin 17, 18 and 27 are reserved by it.
With that configuration, we create 5 extra busses, which are respectively: bus 7 (SDA pin 5 and SCL pin 6), bus 6 (SDA pin 13 and SCL pin 19), bus 5 (SDA pin 12 and SCL pin 16), bus 4 (SDA pin 20 and SCL pin 21), bus 3 (SDA pin 17 and SCL pin 27).
  • We must restart the Raspberry Pi. To do this, type the following command into the terminal on your Raspberry Pi.
sudo reboot
[$[Get Code]]
  • You can verify if the sensors are working by typing the following line in the terminal of the rasperry pi:
sudo i2cdetect -y 3
sudo i2cdetect -y 4
sudo i2cdetect -y 5
sudo i2cdetect -y 6
sudo i2cdetect -y 7
[$[Get Code]]
You should see one sensor on each bus with the adress #29

Set up the wifi access point

reference

  • In order to work as an access point, the Raspberry Pi needs to have the hostapd access point software package installed:
sudo apt install hostapd
[$[Get Code]]
  • Enable the wireless access point service and set it to start when your Raspberry Pi boots:
sudo systemctl unmask hostapd
sudo systemctl enable hostapd
[$[Get Code]]
  • In order to provide network management services (DNS, DHCP) to wireless clients, the Raspberry Pi needs to have the dnsmasq software package installed:
sudo apt install dnsmasq
[$[Get Code]]
  • Finally, install netfilter-persistent and its plugin iptables-persistent. This utility helps by saving firewall rules and restoring them when the Raspberry Pi boots:
sudo DEBIAN_FRONTEND=noninteractive apt install -y netfilter-persistent iptables-persistent
[$[Get Code]]

Set up the network router

The Raspberry Pi will run and manage a standalone wireless network. It will also route between the wireless and Ethernet network, providing internet access to wireless clients when the wired network interface is connected to the web.

Define the wireless interface IP configuration

The Raspberry Pi runs a DHCP server for the wireless network; this requires static IP configuration for the wireless interface (wlan0) in the Raspberry Pi. The Raspberry Pi also acts as the router on the wireless network. We give the router the first IP address in the network: 192.168.5.1.

  • To configure the static IP address of the WiFi interface, edit the configuration file for dhcpcd with:
sudo vim /etc/dhcpcd.conf
[$[Get Code]]
  • Go to the end of the file and add the following:
interface wlan0
static ip_address=192.168.5.1/24
nohook wpa_supplicant
[$[Get Code]]

Enable routing and IP masquerading

This section configures the Raspberry Pi to let wireless clients access computers on the main (Ethernet) network, and from there, to access the internet (if the wired interface is connected to the web). NOTE: If you prefer to block wireless clients from accessing the Ethernet network and the internet, skip this section.

  • To enable routing, i.e. to allow traffic to flow from one network to the other in the Raspberry Pi, create a file using the following command, with the contents below:
sudo vim /etc/sysctl.d/routed-ap.conf
[$[Get Code]]
  • File content:
# https://www.raspberrypi.org/documentation/configuration/wireless/access-point-routed.md
# Enable IPv4 routing
net.ipv4.ip_forward=1
[$[Get Code]]

Enabling routing will allow hosts from network 192.168.5.0/24 to reach the LAN and the main router towards the internet. In order to allow traffic between clients on this foreign wireless network and the internet without changing the configuration of the main router, the Raspberry Pi can substitute the IP address of wireless clients with its own IP address on the LAN using a "masquerade" firewall rule.

The main router will see all outgoing traffic from wireless clients as coming from the Raspberry Pi, allowing communication with the internet. The Raspberry Pi will receive all incoming traffic, substitute the IP addresses back, and forward traffic to the original wireless client.

  • This process is configured by adding a single firewall rule in the Raspberry Pi:
sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
[$[Get Code]]
  • Now save the current firewall rules for IPv4 (including the rule above) and IPv6 to be loaded at boot by the netfilter-persistent service:
sudo netfilter-persistent save
[$[Get Code]]

Filtering rules are saved to the directory /etc/iptables/. If in the future you change the configuration of your firewall, make sure to save the configuration before rebooting.

Configure the DHCP and DNS services for the wireless network

The DHCP and DNS services are provided by dnsmasq. The default configuration file serves as a template for all possible configuration options, whereas we only need a few. It is easier to start from an empty file.

  • Rename the default configuration file and edit a new one:
sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
sudo vim /etc/dnsmasq.conf
[$[Get Code]]
  • Add the following to the file and save it:
interface=wlan0 # Listening interface
dhcp-range=192.168.5.2,192.168.5.20,255.255.255.0,24h
# Pool of IP addresses served via DHCP
domain=wlan # Local wireless DNS domain
address=/lan3v2/192.168.5.1
# Alias for this router
[$[Get Code]]

The Raspberry Pi will deliver IP addresses between 192.168.5.2 and 192.168.5.20, with a lease time of 24 hours, to wireless DHCP clients.

There are many more options for dnsmasq; see the default configuration file (/etc/dnsmasq.conf) or the online documentation for details.

Ensure wireless operation

Countries around the world regulate the use of telecommunication radio frequency bands to ensure interference-free operation. The Linux OS helps users comply with these rules by allowing applications to be configured with a two-letter "WiFi country code", e.g. US for a computer used in the United States.

In the Raspberry Pi OS, 5 GHz wireless networking is disabled until a WiFi country code has been configured by the user, usually as part of the initial installation process.

  • To ensure WiFi radio is not blocked on your Raspberry Pi, execute the following command:
sudo rfkill unblock wlan
[$[Get Code]]

This setting will be automatically restored at boot time. We will define an appropriate country code in the access point software configuration, next.

Configure the access point

  • Create the hostapd configuration file, located at /etc/hostapd/hostapd.conf, to add the various parameters for your wireless network.
sudo vim /etc/hostapd/hostapd.conf
[$[Get Code]]
  • Add the information below to the configuration file. This configuration assumes we are using channel 7, with a network name of LAN3V2, and a passphrase lan3v2wifi. Note that the name and password should not have quotes around them. The passphrase should be between 8 and 64 characters in length.
country_code=CA
interface=wlan0
ssid=lan3v2
hw_mode=g
channel=7
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=lan3v2wifi
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP
[$[Get Code]]

Note the line country_code=CA: it configures the computer to use the correct wireless frequencies in Canada. Adapt this line and specify the two-letter ISO code of your country. See Wikipedia for a list of two-letter ISO 3166-1 country codes.

To use the 5 GHz band, you can change the operations mode from hw_mode=g to hw_mode=a. Possible values for hw_mode are:

a = IEEE 802.11a (5 GHz)
b = IEEE 802.11b (2.4 GHz)
g = IEEE 802.11g (2.4 GHz)
ad = IEEE 802.11ad (60 GHz)
[$[Get Code]]

Run your new wireless access point

  • Now restart your Raspberry Pi and verify that the wireless access point becomes automatically available.
sudo systemctl reboot
[$[Get Code]]

Once your Raspberry Pi has restarted, search for wireless networks with your wireless client. The network SSID lan3v2 should now be present, and it should be accessible with the password lan3v2wifi.

If SSH is enabled on the Raspberry Pi, it should be possible to connect to it from your wireless client as follows, assuming the pi account is present: ssh sand@192.168.5.1 or ssh sand@lan3v2

Configure the network parameters of the raspberry pi

  • Edit the file /etc/dhcpcd.conf
sudo vim /etc/dhcpcd.conf
[$[Get Code]]
  • Uncomment the section related to the static ip configurations but set ip address to 192.168.0.100 i.e.
# Example static IP configuration:
interface eth0
static ip_address=192.168.0.100/24
static ip6_address=fd51:42f8:caae:d92e::ff/64
static routers=192.168.0.1
static domain_name_servers=192.168.0.1 8.8.8.8 fd51:42f8:caae:d92e::1
[$[Get Code]]

UPS hat

The UPS is a power battery backup. It will protect the system against power fluctuations and will allow the system to continue its ongoing tasks during short power failure.

  • To enable the up, edit the file /etc/rc.local
sudo vim /etc/rc.local
[$[Get Code]]
  • Add a line before the exit 0 with the following content:
/usr/local/bin/ups.sh &
/usr/local/bin/web-preview.bash &
[$[Get Code]]

The script web-preview.bash that will start on boot. This script aim to create a page showing the latest recorded readings from a web browser. The data is updated every 5 seconds.

Automatic startup of lan3v2.py code

sudo cp start.service /etc/systemd/system
sudo systemctl enable start.service
sudo systemctl start start.service
[$[Get Code]]

System reboot

Now all the relevant software are installed, in order to activate all newly added functionalities, restart the computer.

$StopWatch