Precision Pendulum Assembly: Software management

This page contains the instruction set and most software utilities used in the remote experiment controller and the way it is connected to the internet.

Raspberry software

Software management

The Raspberry Pi computer interfaces the experiment micro-controller and the e-lab servers. Without it, no remote access is possible. It's, therefore, essential it is properly setup and configured to ensure high reliability and safety.

Operating System Installation

Should you start with a blank SD card, the first task is to install the Operating System (OS). There are several OSes supporting the Raspberry Pi (RPi) available and, in theory, any of those supporting the needed software can be used. However the use of Raspbian is highly recommended. It's the official OS from the Raspberry Pi Foundation for all RPi models, it has a wide selection of supported software available on the official repositories and tutorials and guides abound, online and in other mediums.

Instructions below this point assume that Raspbian is being used. Other OSes may have different configuration methods.

When creating a new SD card, the latest version of the OS should be installed. This ensures that the system is going to run with all the available security and performance fixes available. The latest version of Raspbian can be downloaded from this link. Three versions are available:

• The lite version contains the minimal amount of software needed to boot the RPi. No extra software is included. This implies the lack of a Graphical User Interface (GUI), meaning that, if connected to a display, the RPi will show only a command line (as pictured).
• The desktop version contains the same software as the lite version plus the software needed to use a GUI. When connected to a display, the RPi will show a GUI (pictured).
• The desktop and recommended software version contains the same software as the desktop version plus some pre-selected software and utilities.

The same software is available for installation on all versions, meaning that one can start with a lite version and later install all the software included in the desktop and recommended software version. If the RPi is being prepared to run solely as a server for the experiment, it's recommended that the lite or desktop version is chosen, as having an OS with only the needed software is safer, improves performance and maintainability. In particular, if you plan to use the RPi without a display, the lite version is of special interest as it doesn't package the GUI, which is only useful if you use a display.

The Raspberry Pi Foundation provides installation instructions for the Raspbian OS here.

After Installation

After installing the OS, the SD card is now ready to be used to boot the RPi. However, before inserting the SD card on the RPi, one needs to consider how to interface it the RPi. It's possible to do so through two different methods, as follows:

Using the RPi through a keyboard, mouse and display

When using a keyboard, mouse and display, the RPi works just like any other computer. Since it's possible to interface with the RPi through the keyboard, mouse and display, the SD card can be inserted into the RPi and the boot process can be started by connecting the power adapter to the RPi. This is a simpler procedure, however the extra hardware needed makes it more expensive. Do not connect the RPi to the internet before completing the OS configuration, as described below. When successfully setup, you should see either a prompt showing:

pi@raspberry:~ $

or the usual graphical user interface of the OS, depending on the version of Raspbian chosen.

Proceed to the RPi Operating System Configuration section.

Connecting to the RPi through a ssh connection

If a keyboard, mouse and display are not available to use and interact with the RPi, it's still possible to interact with it by setting up the SSH service before inserting the SD card into the RPi. The SSH service allows connections with a RPi via a network interface, through which commands can be sent. This makes use of the keyboard, mouse and display of a second computer, e.g. a already setup laptop or desktop computer. To do so, the Raspberry Pi and the computer used need their network setting to be adjusted.

To enable the SSH service on the RPi externally:

• Insert the SD card into a computer, e.g. the one used to install the OS on the card.
• After installing the OS, the card will show on computers as being composed of two drives. A smaller drive of a few hundred MBs and a larger drive of a few GBs (depending on the size of the SD card).
• On the smaller "drive", create an empty file called ssh. This enables the SSH service during the next boot of the RPi only. This setting will be made permanent later.
• On the bigger "drive", edit the file "/etc/dhcpcd.conf". On the end of the file, there should be a section of text similar to this:

# It is possible to fall back to a static IP if DHCP fails:
# define static profile
profile static_eth0
static ip_address=123.123.123.123/24
#static routers=192.168.1.1
#static domain_name_servers=192.168.1.1

# fallback to static profile on eth0
interface eth0
fallback static_eth0

Edit the file so it mimics the text shown above. The line:

static ip_address=123.123.123.123/24

Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through DHCP. In general, this happens when no connection is available on the network or it has been connected to a common laptop or desktop computer. Other fallback IP's other than 123.123.123.123 can be chosen. This one is suggested as it's easy to remember.

• The SD card can now be safely unmounted from the computer and inserted into the Raspberry Pi and booted

Next, the computer that will connect to the RPi must have it's own Ethernet connection configured so it connects to the same subnet as the RPi. This means that, following the configuration shown above, its' IP should be configured to be 123.123.123.xxx, where the last number can be any from 001 to 254, and a netmask of 255.255.255.000. The exact procedure to follow to accomplish this is highly dependent on the OS installed on the computer. Be sure to proceed in a way appropriate for your specific OS. If your computer uses the Ethernet port for day-to-day internet connection, it's possible that some specific configuration is attributed to it to make this connection possible on your network. Be sure to preserve the original network settings of your Ethernet adapter so you can rollback any changes made, by either taking screenshots of the appropriate dialogs or taking notes. Below are some examples for common OSes.

Configuring the Ethernet Adapter on Windows 10/8.1/7 and connecting to the RPi

• Microsoft provides instructions on how to manually configure the Ethernet adapter.
• Follow the procedure for manually configuring IPv4 settings. When prompted, fill the IP Address field with an appropriate address according to the configuration selected for the RPi. Assuming the example configuration shown on this page was selected, this field can be filled with 123.123.123.124, and the field Subnet prefix length/Subnetmask can be filled either with 255.255.255.0 or 24. Settings regarding the Gateway and DNS fields and IPv6 can be ignored.
• If not done so before, the RPi can be booted and connected to the computer through Ethernet. This is accomplished by connecting one end of an Ethernet cable to the Ethernet port of the computer and the other end of the cable to the Ethernet port of the RPi.
• The network symbol on the Windows tray should now show the Ethernet connection. Possibly stating it is an unknown network.
• Windows does not install a SSH client by default. To connect to the RPi via SSH one must be set up. Although others can be used, putty is an open source, free software SSH client for Windows. It can be installed or used as standalone, meaning no install necessary. The following steps will follow the use of putty. Be aware that although the general configuration also applies to other software, specific instructions may differ.
• Fill the field Host Name (or IP Address) with the configured IP of the RPi. If the suggested configuration is being followed, this should be filled with 123.123.123.123. On the radio buttons below, select SSH. If you wish to save this configuration so that it's not needed to remember or rewrite it every time, write any memorable name on the field Saved Sessions and click Save. You can then retrieve this settings by selecting the name from the list and selecting Load.
• A warning can appear stating that the host, the computer you're connecting to, is new and unknown. You'll be asked if the new computer can be trusted and the connection completed. Since this a fresh install of a computer you own and have setup by yourself, you can safely answer yes. When prompted, input the password. If this is not the first time following this guide, it's possible that the warning states that the host, the computer you're connecting to, has changed. This is expected as you can now be applying theses steps to a different RPi. Accept the warning by selecting Yes and the connection should be completed.
• When prompted for the user and password, input the default user and password of the Raspian OS which can be found here.
• Note that in this case pi and 123.123.123.123 are used since we're connecting to the RPi as user pi and it's directly connected to the computer with the configured IP of 123.123.123.123. After creating a new user and deleting the default one and connecting the RPi to regular network, this will change.
• After successfully inputting the default password, a prompt will be shown stating:

pi@raspberry:~ $

You have logged in successfully and can now proceed to the RPi Operating System Configuration

• If there was an error stating

ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host

where xxx.xxx.xxx.xxx is the IP used in the ssh command, the Ethernet adapters have been misconfigured. Please, revisit the configuration of the adapters. For a successful connection both the computer and the RPi must be configured to be in the same subnet. If you haven't followed the IP configuration suggested here, please note it is known to provide a functional set up.

Configuring the Ethernet Adapter on Linux using Network Manager and connecting to the RPi

• Linux isn't a monolithic OS. What is generally know as Linux is a set of several distributions, also know as distros, that build an OS on the same basis, the Linux kernel. Depending on the distro used, the specific procedure to follow will differ. The following procedure applies to distros that have Network Manager setup to manage connectivity. This is the case for most of the popular distros, such as Ubuntu and its flavours, Linux Mint, Fedora, etc.
• Right click on the Network Manager icon and select Edit connections
• Click on the + sign on the bottom left of the window, select Ethernet on the dialog shown and click Create. By creating a new configuration, the settings used for regular internet access are preserved, making it easier to roll back the changes.
• The Name field can be filled with any name, although it's recommended to write an easy to remember one, such as Raspberry or Ethernet RPi.
• Select the IPv4 Settings tab and, on the Method dropdown menu, select Manual.
• Click Add next to the Adresses table and, when prompted, fill the Address field with an appropriate address according to the configuration selected for the RPi. Assuming the example configuration shown on this page was selected, this field can be filled with 123.123.123.124, and the neighboring field Netmask can be filled either with 255.255.255.0 or 24.
• The rest of the fields can be safely ignored. Click Save to save the new connection settings. The new settings will now appear on the list with the name selected.
• If not done so before, the RPi can be booted and connected to the computer throught Ethernet. This is accomplished by connecting one end of an Ethernet cable to the Ethernet port of the computer and the other end of the cable to the Ethernet port of the RPi
• The Network Manager icon should now show a spinning symbol, as it tries to connect to the RPi. Click on the Network Manager symbol and on the menu select the Ethernet connection with the name chosen before. The connection should now be set up.
• Most Linux distros include SSH client software on the default OS install, making it unnecessary to install any additional software. SSH commands follow the syntax ssh user@ip or ssh user@hostname. The default user and password of the Raspian OS can be found here. To connect to the RPi, open a terminal on the computer and write

ssh pi@RPI ADDRESS

RPI ADDRESS should be replaced by the IP address selected for the RPi on the previous section. Assuming the configuration suggested was followed, the command should be

ssh pi@123.123.123.123

Note that in this case pi and 123.123.123.123 are used since we're connecting to the RPi as user pi and it's directly connected to the computer with the configured IP of 123.123.123.123. After creating a new user and deleting the default one and connecting the RPi to regular network, this will change.

• A warning can appear stating that the host, the computer you're connecting to, is new and unknown. You'll be asked if the new computer can be trusted and the connection completed. Since this a fresh install of a computer you own and have setup by yourself, you can safely answer yes. When prompted, input the password. If this is not the first time following this guide, it's possible that the warning states that the host, the computer you're connecting to, has changed. This is expected as you can now be applying theses steps to a different RPi. Edit the file stated on the warning and delete the line starting with the IP of the RPi. If the example configuration is being followed, this will be the line starting with 123.123.123.123. Attempt to reconnect by using the SSH command again. You should now see the warning stating this is a new, unknown computer.
• After successfully inputting the default password, a prompt will be shown stating:

pi@raspberry:~ $

You have logged in successfully and can now proceed to the RPi Operating System Configuration

• If there was an error stating

ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host Where xxx.xxx.xxx.xxx is the IP used in the ssh command, the Ethernet adapters have been misconfigured. Please, revisit the configuration of the adapters. For a successful connection both the computer and the RPi must be configured to be in the same subnet. If you haven't followed the IP configuration suggested here, please note it is known to provide a functional set up.

Configuring the Ethernet Adapter on MacOS Catalina/Mojave/High Sierra and connecting to the RPi

• Apple provides instructions on how to manually configure the Ethernet adapter.
• Follow the procedure for manually configuring IPv4 settings. When prompted, fill the IP Address field with an appropriate address according to the configuration selected for the RPi. Assuming the example configuration shown on this page was selected, this field can be filled with 123.123.123.124, and the field Subnetmask can be filled either with 255.255.255.0 or 24. Settings regarding the Gateway and DNS fields and IPv6 can be ignored.
• If not done so before, the RPi can be booted and connected to the computer throught Ethernet. This is accomplished by connecting one end of an Ethernet cable to the Ethernet port of the computer and the other end of the cable to the Ethernet port of the RPi
• The network symbol should now show the connection as being completed.
• MacOS includes a SSH client on the default OS install, making it unnecessary to install any additional software. SSH commands follow the syntax ssh user@ip or ssh user@hostname. The default user and password of the Raspian OS can be found here. To connect to the RPi open a terminal on the computer, and write

ssh pi@RPI ADDRESS

RPI ADDRESS should be replaced by the IP address selected for the RPi on the previous section. Assuming the configuration suggested was followed, the command should be

ssh pi@123.123.123.123

Note that in this case pi and 123.123.123.123 are used since we're connecting to the RPi as user pi and it's directly connected to the computer with the configured IP of 123.123.123.123. After creating a new user and deleting the default one and connecting the RPi to regular network, this will change.

• A warning can appear stating that the host, the computer you're connecting to, is new and unknown. You'll be asked if the new computer can be trusted and the connection completed. Since this a fresh install of a computer you own and have setup by yourself, you can safely answer yes. When prompted, input the password. If this is not the first time following this guide, it's possible that the warning states that the host, the computer you're connecting to, has changed. This is expected as you can now be applying theses steps to a different RPi. Edit the file stated on the warning and delete the line starting with the IP of the RPi. If the example configuration is being followed, this will be the line starting with 123.123.123.123. Attempt to reconnect by using the SSH command again. You should know see the warning stating this is a new, unknown computer.
• After successfully inputting the default password, a prompt will be shown stating:

pi@raspberry:~ $

You have logged in successfully and can now proceed to the RPi Operating System Configuration

• If there was an error stating

ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host Where xxx.xxx.xxx.xxx is the IP used in the ssh command, the Ethernet adapters have been misconfigured. Please, revisit the configuration of the adapters. For a successful connection both the computer and the RPi must be configured to be in the same subnet. If you haven't followed the IP configuration suggested here, please note it is known to provide a functional set up.

RPi Operating System Configuration

After installation, the OS needs to be configured. The following instructions are to be followed on the terminal prompt. If you are using a keyboard and display connected to the RPi and installed an OS with GUI, please open a terminal emulator.

First, proceed with general system configuration by loading the raspi-config utilty, executing the command:

sudo raspi-config

When prompted input user's pi password. The menu that shows can be navigated using arrow keys for selection, escape key for moving backwards on the menus and enter to select the highlighted entry.

• The 1 Change User Password entry can be ignored as the pi user will be deleted later

• On the 2 Network Options entry, it's possible for the Hostname to be set and a Wi-fi connection to be configured.

The Hostname is the name assigned to the RPi and has no special meaning. It's helpful for easy recognition of the computer based only on name.

The Wi-fi entry allows the configuration of a Wi-fi network by entering the SSID (network name) and network password. This dialog only works for WEP, WPA and WPA2 schemes. WPA-entreprise must be manualy setup through the wpa_supplicant.

Ignore the remaining entries unless certain about the changes being performed.

• On the 3 Boot Options, it's the Desktop / CLI entry selects whether the RPi boots into a GUI environment or into a command prompt, the Wait for Network at Boot if it waits for network connection before completing the boot process and the Splash Screen if it shows an image or debugging text during boot.

Be aware that the Desktop / CLI entry only produces effects if you previously installed a version of Raspbian with GUI or have meanwhile installed a GUI on the lite version.

These settings are safe to setup according to users wishes.

• On the 4 Localisation Options entry, the Change Locale entry allows setting up the RPi so it's diplayed language, and other localisation elements, such as time and date format, name of days of the wiki, currency, etc, are according the RPi user's location, the Change Timezone entry allows setting the local timezone, so that the RPi shows the correct time and date, the Change Keyboard Layout entry allows the user to set up it's keyboard so that the keys typed in the physical keyboard match the ones that appear on screen, and the Change Wi-fi Country sets up the RPi so it's communicating on the right Wi-fi frequencies according to the local laws.

The Change Keyboard Layout entry is only important if the RPi is used with a keyboard directly connected to it. Users connecting through SSH do no need to configure this setting.

The Change Wi-fi Country entry must be configured if a Wi-fi connection is to be setup. Failure to do so may result in a non-working connection, as the RPi is trying to communicate in different frequencies as the rest of the local Wi-fi devices, and regulatory issues for the user for transmitting in prohibited frequencies.

• On the 5 Interfacing Options, the entries allow enabling/disabling the various listed services. All should be configured to disabled except for the SSH and/or VNC services, the Serial interface and Remote GPIO access.

Be aware that the VNC service will only work if a GUI is installed on the system. If not, only the SSH' service can be enabled.

Enabling the SSH service makes it unnecessary to create the ssh file on disk as described before. It will be available on every boot until disabled again.

On the Serial entry, please select No when prompted if the login shell should be available over serial.

• Please ignore the remaining options, except for the Expand Filesystem option available on the Advanced Options entry.

• Exit the utility by selecting Finish and, when prompted, allow the RPi to reboot by selecting yes. If connected via SSH, the connection will be automatically terminated.

• Allow the RPi to finish rebooting. Do not power it off by disconnecting the power cable.

• When the green led has stopped flashing, the reboot is complete. Login into the RPi as before.

Before connecting the RPi to the internet, a new user must be to created and the the default user must be deleted. Since all fresh Raspbian OS installs have the same default user and password, that everyone can find on the internet, keeping them available on the OS is a very serious security vulnerability. Anybody that knows this is free to try to login into your RPi and, if successful, take control of the system.

The following commands create an user named newton. Other usernames can, and should be, chosen when configuring the RPi. The username newton is being used as an example.

• Create user newton

sudo useradd newton

When prompted to input user pi's password, input the same password used to login. This will start the user creation process where a new password for the new user is going to be asked for. Choose a new password, different from the default pi user password. When choosing the new password please remember that:

Strong passwords have at least 8 characters, a mixture of both uppercase and lowercase letters, a mixture of letters and numbers and include at least one special character, e.g., ! @ # ? ].

A strong password is hard to guess, but it should be easy to remember. A password that has to be written down is not strong, no matter how many of the above characteristics are employed.

Do not choose passwords that are composed of any word that can be found in a dictionary, in any language (e.g., airplane or aeroplano), a dictionary word with some letters simply replaced by numbers (e.g., a1rplan3 or aer0plan0), a repeated character or a series of characters (e.g., AAAAA or 12345), a keyboard series of characters (e.g., qwerty or qazwsx), anything that’s written down and stored somewhere near your computer.

Your username and password are one of the main mechanisms of defense against unauthorized access and tampering. Having easy to guess usernames, weak passwords or having them known to the public severely impacts the security of your devices and network.

• Add the new user to the system groups

Start by identifying the groups the original user pi is a member of by executing the command:

id

The command will output three lists in the format number(text). Keep the output on screen. Write, but don't execute, the following command:

sudo usermod -a -G

From the previous command output, select the list after groups=, except for the first element, by clicking and dragging with the mouse over the text. Copy it to the command line by clicking the middle mouse button after selecting the text. Edit the current command by using the arrows on the keyboard to move the cursor and removing the numbers and parenthesis but keeping the text and commas. Add the name of the user being created to the end of the command. The final command should have the same format as this:

sudo usermod -a -G group1,group2,group3,group4 newton

Confirm that the user was successfully added to the system groups by executing:

id newton

In the output, after groups=, the same groups as above should appear. Do not proceed before they do.

• Log out from the RPi and login using the new user

• Delete the pi user account

The default user pi still exist in the system. Leaving this account active is a security vulnerability. Delete it by executing:

sudo userdel -remove-home pi

• In order to configure the network where the RPi will be connected, it's often useful to know the MAC address of the network adapter. Execute the following command:

ifconfig

If planning to connect the experiment via Ethernet cable, copy the ether field on the eht0 entry of the output. If connecting via wireless connection, copy the ether field on the wlan0 entry of the output.

• If planning to use a VPN connection to manage remotely deployed experiments, now is also a good time to send the needed files to the RPi. Doing so ensures the needed secrecy of the keys, as they are sent through the cable that connects your computer and the RPi. If using the RPi with keyboard and display, consider shutting it down and writing the files directly on the sd card by inserting it on a computer. VPN configuration is highly dependent on your setup, so it should be completed on case by case basis.

• If not done so, shutdown the RPi. Wait for the green led on the RPi to stop blinking before disconnecting the power source. Move it to its permanent location, connecting it to experiment's electronics and network infrastructure.

• Turn on the RPi by connecting the power source. It should obtain a valid IP adress from your network. Network and firewall configuration is highly dependent on your specific network infrastructure. If the above instructions were followed, the RPi is configured to accept DHCP IP lease offers. In order for the hardware server and the video streaming to work, the RPi must be able to communicate

• Login into it. Update the software on the RPi by running the following commands in succession:

sudo apt-get update
sudo apt-get full-upgrade

The last command can take a while to complete. While it works, DO NOT DISCONNECT THE RPi FROM THE POWER SOURCE. IF YOU DO, YOU'LL MOST LIKELY CORRUPT THE SD CARD AND YOU'LL HAVE TO START ANEW.

• Reboot the RPi to ensure the latest software is running. Log into it again.

• Install the needed software for the hardware server and the video streaming.

For the hardware server, the following software should be installed:

sudo apt-get install openjdk-8-jre-headless librxtx-java

For the video streaming, various software could be used. The recommend way is to use GStreamer and its libraries that support video hardware enconding on the RPi. It can be installed by the following command:

sudo apt-get install gstreamer1.0-tools gstreamer1.0-plugins-ugly gstreamer1.0-plugins-good gstreamer1.0-plugins-base gstreamer1.0-plugins-bad\
gstreamer1.0-omx-rpi gstreamer1.0-omx-rpi-config gstreamer1.0-omx-generic gstreamer1.0-omx-generic-config

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:

sudo apt-get install openvpn

Now that the VPN is install, complete the configuration of the VPN with the files transfered to the RPi on the last step.

Please note that the software manager will suggest extra packages, mostly dependencies of the ones explicited ordered to install. Accept any extra suggested packages.

Known Serial Port problems

In releases and updates after 9/2018 we have detected that the serial internal port can read erroneous characters due to a failure in synchronicity (small slip in frequency). Unfortunately things changed a bit with the current version of the Jessie operating system for the Raspberry Pi 3. First the serial port name ttyAMA0 reserved until now for the GPIO serial communication was stolen by the Bluetooth driver. The GPIO serial port name is ttyS0 now. Second and more annoying is the fact that the serial port is not functioning because of the higher CPU core clock frequency.

To our best knowledge it can be sort out by (i) disable as mentioned before the serial console and (ii) editing the file /boot/config.txt as sudo in the nano editor

sudo nano /boot/config.txt

and add at the bottom the line

core_freq=250

Then reboot:

sudo reboot

You can get information about the names of all serial ports with the command

dmesg | grep tty

If you find the text for Raspberry Pi 3:

console [ttyS0] enabled

the console is not disabled as it should.

Network tools and utilities

The connectivity of the computer were the hardware server will be installed can be tested and verified by installing some tools such as nmap:

sudo apt-get install nmap

The nmap program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:

nmap -v -A elab.ist.utl.pt

Ports 443, 80, 8080, 22, and [9000..9010] are expected to be open. elabmc should have added the UDP ports for streaming (see last section).

We suggest to use the cron utility in case a regular reboot is required. To avoid simultaneous registration requests at the same time a delay of 5 minutes is added according to the experiment order. Nano is the elected editor.

sudo crontab -e

and the following line is added to reboot every 4 am plus 35 minutes (position 7 on the table)

0 4   *   *   *    /sbin/shutdown -r +35

Contab -l lists the jobs to be run at a particular time.

sudo crontab -l

Install a OpenVPN certificate

If your certificate becomes invalid to allow your system to login on elab OpenVPN you can retrieve a recent one by issuing the following command:

echo "get ca.crt" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist

Here you should use the remote system elab1 password.

Then you need to move it to the OpenVPN directory which has admin privileges:

sudo mv ./ca.crt /etc/openvpn/privnet

Please enter the local wpa user password.

Finally just *reboot* the system to take effect.

Autonomous codes

Hardware Server

Now that you have the Raspberry Pi and the Pendulum all set up, you are ready to connect it to the World Pendulum Alliance network.

In order to do that you will need to deploy and run an application on the Raspberry. This application is called REC Hardware Server, it is a Java application and that is why it is necessary to have the JDK installed.

Once you run the REC Hardware Server, it will automatically try to contact your Pendulum where it is expecting to find its ID String (e.g. "WP_UESC_IOS"). If it finds the expected ID, it will then connect with the Pendulum and your pendulum should come alive at elab public page. Otherwise it will output an error message, in which case we advise you to contact the project management team to help with the debugging.

The REC Hardware Server specific for your pendulum will be provided by the project coordination in a .ZIP file, that will be made available at a specific folder at elab1 server.

To deploy a new version of the REC Hardware Server for a specific pendulum you should open a terminal (e.g. Putty) and access the machine where the Hardware Server will be deployed - in this case, the RPi - and follow these steps:

• Validate if the "rec-deployment" directory exists, if not, create it by typing:
  

  mkdir ${home_directory}/rec-deployment 

  ex: mkdir /home/wpa/rec-deployment 

• List HardwareServer Zip files:
  

  echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist

• Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry):
  

  echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist 

  ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist 

Go to rec-deployment directory:


cd /home/wpa/rec-deployment 

• Unzip HardwareServer's zip file to rec-deployment directory

  unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}

  ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios

• Change to directory of experience:

  cd ${hardwareServerAliasName}

  ex: cd wpuescios

• Start HardwareServer:

  ./Start${AliasName}Driver.sh

  ex: ./StartwpuesciosDriver.sh

  NOTE

  The HardwareServer should only be deployed after the complete calibration procedure described on the next page and executed with the minicom or other terminal program.

  Video Streaming

  The video streaming can be done by using the picamera, the RPi proprietary camera, or a common USB camera. The following steps were tested on a USB camera. Furthermore, they were designed to work with a streaming server that receives the video from the RPi and resends it to all connected clients.

  • Start the streaming on the RPi. This is done with the command:

  gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=320,height=240,framerate=10/1 ! clockoverlay time-format="%x - %X" \
  ! videoconvert ! omxh264enc ! video/x-h264,profile=baseline ! h264parse ! mpegtsmux ! rtpmp2tpay ! udpsink host=HOST port=PORT async=false

  Although it is almost certainly on /dev/video0, it's possible that the camera does not show on the RPi system on /dev/video0. Verify that it is by running:

  ls /dev
  

  On the output, the entry of the format videoX, where X is a number, is the logical location of the camera on the system. Edit the command above so that the number X is the same as the one listed on the output of the last command.

  It's possible to increase the resolution of the video and the framerate by altering the width, height and framerate fields on the example command above. The example values shown above are very conservative but ensure that video streaming is possible even in the toughest network conditions by generating a very low bitrate stream. Note that any width, height and framerate asked for needs to be supported by the video camera, otherwise the command will return with an error. Edit the HOST and PORT fields so they point to your particular video streaming server.

  Once it's verified that the video is running, it can be made permanent by slightly altering the command to:

  nohup gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=320,height=240,framerate=10/1 ! clockoverlay time-format="%x - %X" \
  ! videoconvert ! omxh264enc ! video/x-h264,profile=baseline ! h264parse ! mpegtsmux ! rtpmp2tpay ! udpsink host=HOST port=PORT async=false &

  This will run until the RPi is shutdown or the camera is disconnected.

  Specific Instructions for the World Pendulum Alliance Project

  A List of TCP ports is deemed necessary to be open for the correct internet connection between the apparatus' computer and the central server.

  For the main partner pendulums, the HOST parameter of the streaming command should be set as instructed on the training sessions. The PORT should be set as indicated on Port listing page. For each secondary pendulum, the same process may be followed. However, partners must set up independent streaming infrastructure for secondary pendulums video streaming.

  In order to make the needed information available for users to be able to connect to the stream, SDP files must be made available. These can then be independently opened on video player software, like VLC, or seen through the pendulum client software. The file can be made by adapting the template below, replacing the EXPERIMENT NAME and PORT by the appropriate fields, as shown on the Port listing page. The HOST field should be set to the same value as described on the training sessions.

  v=0
  o=- 16251185917537979632 16251185917537979632 IN IP4 EXPERIMENT NAME
  s=EXPERIMENT NAME
  i=N/A
  c=IN IP4 HOST
  t=0 0
  a=tool:vlc 3.0.8
  a=recvonly
  a=type:broadcast
  a=charset:UTF-8
  m=video PORT RTP/AVP 33
  b=RR:0
  a=rtpmap:33 MP2T/90000
  

  The SDP file should be created with the same name as indicated on the Port listing page. This file must then be transferred to the server responsible for making it available to the web as instructed on the training sessions.

  
  In case ttyS0 is not being used, a symbolic linker ca be used if needed:

  ln -s /dev/ttyAMA0 /dev/ttyS0
  

  Automatically Start on RPi Boot

  To make the programs start automatically as the RPi boots, edit the file /etc/rc.local by executing

  sudo nano /etc/rc.local
  

  Assuming the hardware server has been placed on the folder indicated on the previous section, adding the following lines to the file, before the exit 0 and after the fi, will make the RPi start the hardware server and the video streaming automatically as it boots without further intervention.

  sleep 120
  su USER -c "/home/USER/rec-deployment/exp_name/expDaemon.sh start &"
  su USER -c "(gst-launch-1.0 v4l2src device=/dev/video0 ! \
   video/x-raw,width=320,height=240,framerate=10/1 ! \
   clockoverlay time-format=\"%x - %X\" ! \
   videoconvert ! \
   omxh264enc ! \
   video/x-h264,profile=baseline ! h264parse ! \
   mpegtsmux ! rtpmp2tpay ! \
   udpsink host=HOST port=PORT async=false ) &"
  

  Note that the HOST and PORT fields need to be replaced as exampled above. The USER field should be changed to match the user account created, typically wpa as previously instructed.

  In case ttyS0 is not being used, a symbolic linker can be used if needed:

  ln -s /dev/ttyAMA0 /dev/ttyS0
  

  dsPIC firmware

  Program dsPIC with Raspberry Pi

  With the help of a programmer software, the dspic can be programmed using the Raspberry Pi. See this page for instructions.

  Download firmware file

  The official firmware releases available for download are presented below.

  Version 2021_01_06_22_08_46: Wp 2021 01 06 22 08 46.zip

  Source files

  Below is a .zip file that contains the source files corresponding to the WPA firmware version 2021_01_06_22_08_46. A .txt file containing a set of steps to guide the user on how to create a MPLAB X IDE project is also included in the .zip file. The date and time of the compilation is stored in the .hex file. This means that any firmware (.hex) files complied in different dates/times will differ from each other. This feature was introduced to allow a clear distinction of each newly created .hex file.

  source_files.zip

  
  

  Previous Page (Electrical interfaces) Next Page (Calibration)

  Links

  • Portuguese Version (Versão em português)
  • Spanish Version (Versión en español)