wwwelab - User contributions [en]

Precision Pendulum Assembly: Software management

2022-07-28T22:52:25Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[Media:Wp 2021 01 06 22 08 46.zip|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.

[[Media:source_files.zip|source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:51:03Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[Media:Wp 2021 01 06 22 08 46.zip|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 more allow a clear distinction of each newly created .hex file.

[[Media:source_files.zip|source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:47:03Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[Media:Wp 2021 01 06 22 08 46.zip|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 version of a new .hex file corresponds to the date and time of the compilation and such information is stored in the .hex file. This means that any firmware files complied in different dates/times will differ from each other.

[[Media:source_files.zip|source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:39:02Z

Ist155317: /* Download firmware file */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[Media:Wp 2021 01 06 22 08 46.zip|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.

[[Media:source_files.zip|source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:38:33Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[File: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.

[[Media:source_files.zip|source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:35:48Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[File: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.

[[Media:source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:35:08Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[File: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.

[[File:source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:34:56Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[File: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.

[[File:source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

File:Source files.zip

2022-07-28T22:33:24Z

Ist155317: Ist155317 uploaded a new version of File:Source files.zip

File:Source files.zip

2022-07-28T22:30:28Z

Ist155317:

Precision Pendulum Assembly: Software management

2022-07-28T22:29:53Z

Ist155317: /* dsPIC firmware */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_06_22_08_46: [[File: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. In addition, a .txt file containing a set of steps to guide the user on how to create a MPLAB X IDE project is provided.

[[File:source_files.zip]]

[[Media:instructions.txt|instructions.txt]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:25:30Z

Ist155317: /* Source files */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

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

==Source files==
Below is a .zip file that contains the source files for WPA
[[File:source_files.zip]]

[[Media:instructions.txt|instructions.txt]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-07-28T22:23:54Z

Ist155317: /* dsPIC firmware */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

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

==Source files==

[[Media:instructions.txt|instructions.txt]]
[[File:source_files.zip]]

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:50:58Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
The dsPic board consists of a 4 layer PCB. The layouts follow below:

[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

[[Media:INNER1.pdf|INNER1.pdf]]

[[Media:INNER2.pdf|INNER2.pdf]]

[[Media:BOT_NonMirrored.pdf|BOT_NonMirrored.pdf]]

[[Media:BOT2_NonMirrored.pdf|BOT2_NonMirrored.pdf]]

[[Media:BOT_Mirrored.pdf|BOT_Mirrored.pdf]]

[[Media:BOT2_Mirrored.pdf|BOT2_Mirrored.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:50:35Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
The dsPic board consists of a 4 layer PCB.

[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

[[Media:INNER1.pdf|INNER1.pdf]]

[[Media:INNER2.pdf|INNER2.pdf]]

[[Media:BOT_NonMirrored.pdf|BOT_NonMirrored.pdf]]

[[Media:BOT2_NonMirrored.pdf|BOT2_NonMirrored.pdf]]

[[Media:BOT_Mirrored.pdf|BOT_Mirrored.pdf]]

[[Media:BOT2_Mirrored.pdf|BOT2_Mirrored.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:49:38Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

[[Media:INNER1.pdf|INNER1.pdf]]

[[Media:INNER2.pdf|INNER2.pdf]]

[[Media:BOT_NonMirrored.pdf|BOT_NonMirrored.pdf]]

[[Media:BOT2_NonMirrored.pdf|BOT2_NonMirrored.pdf]]

[[Media:BOT_Mirrored.pdf|BOT_Mirrored.pdf]]

[[Media:BOT2_Mirrored.pdf|BOT2_Mirrored.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:BOT2 Mirrored.pdf

2022-07-28T21:49:19Z

Ist155317:

File:BOT Mirrored.pdf

2022-07-28T21:48:31Z

Ist155317:

File:BOT2 NonMirrored.pdf

2022-07-28T21:47:47Z

Ist155317:

File:BOT NonMirrored.pdf

2022-07-28T21:46:51Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:45:19Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

[[Media:INNER1.pdf|INNER1.pdf]]

[[Media:INNER2.pdf|INNER2.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:INNER2.pdf

2022-07-28T21:44:57Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:44:43Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

[[Media:INNER1.pdf|INNER1.pdf]]

[[Media:INNER2.pdf|INNER2.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:INNER1.pdf

2022-07-28T21:44:06Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:30:47Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]

[[Media:TOP2.pdf|TOP2.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:30:31Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]
[[Media:TOP2.pdf|TOP2.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:TOP2.pdf

2022-07-28T21:29:54Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:29:03Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===
[[Media:TOP.pdf|TOP.pdf]]

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:TOP.pdf

2022-07-28T21:27:53Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:25:35Z

Ist155317: /* Schematic */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
[[Media:SBOARD_4L_FULL_V6.pdf|DsPic_board_schematic.pdf]]

===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:SBOARD 4L FULL V6.pdf

2022-07-28T21:24:53Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:24:06Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:22:36Z

Ist155317: /* Layout */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
===Layout===

 

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:20:34Z

Ist155317: /* Overview */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[Media:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:19:41Z

Ist155317: /* Overview */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[File:DsPic_board_overview.pdf|DsPic_board_overview.pdf]]

===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:16:04Z

Ist155317: /* Overview */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[[:File:DsPic_board_overview.pdf]]

===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:15:00Z

Ist155317: /* Overview */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
[DsPic_board_overview.pdf]

===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

File:DsPic board overview.pdf

2022-07-28T21:13:47Z

Ist155317:

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:12:22Z

Ist155317: /* dsPic board */

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==Micro-controller (dsPic) board==
===Overview===
===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Electrical interfaces

2022-07-28T21:10:35Z

Ist155317:

==Electrical interfaces==
This section describes the electrical components used to operate the experimental apparatus. As an overview, each launcher consists of:
* a Raspberry Pi (or computer running Linux): makes the interface between the micro-controller and the human (e.g., direct connection to a console) or e-lab server via Internet.
* a micro-controller (dsPic): makes the interface between the electrical components (including the step-motor) and the computer.
* complementary electrical components: laser, micro-switch, photo-gate (aka photo-diode), light bulb, temperature sensor and 7-digits display.
see [[#Parts|Parts]] for detailed description. These components are the interface between the experimental apparatus and the micro-controller while providing ways of controlling the pendulum as well as measurement capabilities.

See the [[#Connections|Connections]] subsection for details on how to connect the electrical components.

[[File:ComparisonPhotodiodeLDR.png|thum|Comparison in the dispersion error between a photo-diode (StDev=0.002) or LDR (StDev=0.006) photodetector due to slew rate.|right|border|180px]]

The photo-gate/photo-diode and laser alignment is described in subsection [[#Photo-gate and laser alignment|Photo-gate and laser alignment]]. In particular, photo-diodes have been chosen due to their faster transition characteristics, reducing the overall jitter on the photo-gate and consequently the random error.

This is to be performed only after the micro-controller has been powered up, read section [[#Interface console to micro-controller|Interface console to micro-controller]] first.

===Parts===
This subsection presents a description of the different electrical parts of the experiment.
* '''Raspberry Pi (RPi)''': Device running Linux to allow remote connection to the experiment as well as an easy way to interface with the micro-controller. The present micro-controller and corresponding flat cable connections are designed for the Raspberry Pi 3 model B, which has the following pin-out connections as described in https://www.raspberrypi.org/documentation/usage/gpio. The Raspberry Pi is used as well to power the micro-controller, as such a +5 V power supply with at least 2.5 A should be used.
{|
|[[File:rpi.png|x100px]]
|[[File:rpi_ps_1.png|x100px]]
|[[File:rpi_ps_2.png|x100px]]
|}
* '''SD card''': The SD card comes with Linux operating system and all necessary additional programs. This should be an Industrial card with robust specs.
* '''Micro-controller board''': This board contains a micro-controller (dsPic33F) as well as all peripheral components needed for the control of the experiment. The board can be powered using the flat cable connected to the Raspberry Pi or by an USB connection (an onboard jumper is used to select the power source, the default position corresponds to the one from the flat cable/Raspberry source). The board contains 4 LEDs: 2 red, 1 blue and 1 green. The red LEDs indicate if power is connected to the board. Looking to the figures bellow, the red LED on the left corresponds to the +5 V that powers the micro-controller board. The red LED on the right corresponds to the +12 V power that is used to feed the step-motor. The blue and green LEDs (LEDs at the top on the figure) are used for run-time information output by the micro-controller. The blue (left) LED turns on when the micro-switch is pressed, i.e., when the shovel is at the origin. The green (right) LED turns on when the photo-gate is active (conducting), i.e., when it is lit by the laser. The blue and green LEDs are also used for two other cases: (i) at boot and (ii) to indicate that the micro-controller is in an error state. At boot, the LEDs blink 5 times with a period of 400 ms and with alternate states (when the blue LED is ON the green LED is OFF and vice-versa). To indicate an error state, the LEDs blink with a period of about 2 s.
{|
|[[File:dspic_board_closed.png|x100px]]
|[[File:dspic_board_open.png|x100px]]
|[[File:dspic_board_closed_LEDs.jpg|x100px]]
|[[File:dspic_board_LEDs_blue.jpg|x100px]]
|[[File:dspic_board_LEDs_green.jpg|x100px]]
|}
* '''Webcam''': The webcam is used to provide live video streaming during the execution of the experiment. It is connected to the Raspberry Pi via an USB cable. The RPi performs the encoding and then sends it through Internet.
{|
|[[File:webcam.png|x150px]]
|}
* '''Light bulb''': The light bulb consists of a 12 V LED bulb located above the launcher. This bulb turns on during the execution of the experiment to illuminate the pendulum and launcher (specially useful if the experiment is performed during night).
{|
|[[File:light_bulb.png|x125px]]
|}
* '''Step-motor''': The step-motor is part of the launcher and it is controlled by the micro-controller via a quad 1/2 H bridge driver. The step-motor is responsible for the displacement of the shovel.
{|
|[[File:step_motor_1.png|x100px]]
|[[File:step_motor_2.png|x100px]]
|}
* '''Micro-switch''': The micro-switch is located at the origin, close to the 0 cm of the metric scale on the launcher. It is used to indicate the micro-controller that the shovel reached the origin and cannot go further in the backward direction (end of course).
{|
|[[File:ms_1.png|x100px]]
|[[File:ms_2.png|x100px]]
|}
* '''Laser''': The laser is located approximately at the center of the launcher. In conjunction with the photo-gate/photo-diode, the laser is used to measure the oscillation period as well as the location of the shovel. This laser have a regulation for the focus, can be adjusted by rotating the lens.
{|
|[[File:laser_1_crop.jpg|x100px]]
|[[File:Laser_2_crop.jpeg|x100px]]
|[[File:Laser_3_crop.jpeg|x100px]]
|}
* '''Photo-gate (aka photo-diode)''': The photo-gate is located in front of the laser. The bob travels in-between them interrupting the laser light periodically resulting in a change of state at the input pin of the micro-controller. It is then possible to measure the period of the pendulum and the bob velocity by knowing in advance it's diameter. ''NOTE'': Avoid direct sun-light or extreme luminous areas in front of it.
{|
|[[File:ph_gate_1.jpg|x100px]]
|[[File:ph_gate_2_crop.jpg|x100px]]
|}
* '''Temperature sensor''': A temperature sensor is located in the DB25 box to measure the ambient temperature. The ambient temperature influences the length of the pendulum. It is therefore important to monitor this quantity for high precision measurements.
{|
|[[File:temp_sensor_1.jpg|x100px]]
|[[File:temp_sensor_2_crop.jpg|x100px]]
|}
* '''Display''': The 7-digits display shows the total accumulated number of oscillations. It consists of 8 digits, each one a 7 segments display. Some of the micro-controller board versions allow the connection of the display directly on the board from outside of the box.
{|
|[[File:display_loose_crop.jpg|x100px]]
|[[File:display_fixed_crop.jpg|x100px]]
|}
* '''Power supply''': The step-motor requires an external +12 V power supply capable of providing 2 A.
{|
|[[File:ps_1_crop.jpg|x100px]]
|[[File:ps_2_crop.jpg|x100px]]
|[[File:ps_3_crop.jpg|x100px]]
|}
* '''Start button''': The start button allows to locally start an experiment with a predefined configuration (initial displacement of 10 cm, 20 oscillations). An external stopwatch as to be use in complement to provide time.
{|
|[[File:push_button_crop.jpg|x100px]]
|}

===Connections===
This subsection shows how the components and cables are connected between each other.
* '''RPi''': The Raspberry Pi connects to the following:
** Power supply (via micro USB connector)
** Internet (via Ethernet cable)
** Webcam (via USB cable)
** Micro-controller board (via dedicated flat-cable)
{|
|[[File:rpi_connections.jpg|x200px]]
|}
* '''Dedicated flat-cable''': This cable lays down the connection between the micro-controller (dsPic) board, the RPi and the display. At the micro-controller side, the cable has a DB25 connector.
{|
|[[File:flat_cable_DB25_crop.jpg|x150px]]
|}
At the RPi side, the cable has a 2x20 pin connector to ensure a correct connection, see figures below.
{|
|[[File:flat_cable_rpi_1_crop.jpg|x150px]]
|[[File:flat_cable_rpi_2_crop.jpg|x150px]]
|[[File:flat_cable_rpi_3_crop.jpg|x150px]]
|}
At the display end, the connector consist of a 1x5 connector. Please ensure that the connector side is correct before connecting to the display: the VCC pin of the display connects to the wire that is highlighted in this case with a blue trace. See figure below for illustration. Some versions allow the display to be connected directly on the micro-controller box. In such cases, the display should be connected as shown on the right hand side, see figure below.
{|
|[[File:flat_cable_display_crop.jpg|x150px]]
|[[File:display_fixed_crop.jpg|x150px]]
|}
* '''Micro-controller''': The dsPic board connects to the following:
** +12 V power supply to feed the step motor
** RPi (via the flat-cable)
** Electrical components (via dedicated multi-cable)
{|
|[[File:Dspic_board_closed_crop_connections.jpg|x200px]]
|}
* '''Dedicated multi-cable''': The multi-cable connects the dsPic board with electrical components used to perform the experiment. At the dsPic board end, the cable has a DB25 connector as shown in the figure below.
{|
|[[File:multi_cable_DB25_crop.jpg|x150px]]
|}
At the light bulb, micro-switch, laser and photo-gate end, the multi-cable has a 2 pin connector as shown in the following figures:
{|
|[[File:multi_cable_light_bulb_crop.jpg|x75px]]
|[[File:multi_cable_ms_crop.jpg|x75px]]
|[[File:multi_cable_laser_crop.jpg|x75px]]
|[[File:multi_cable_photogate_crop.jpg|x75px]]
|}
At the step-motor end, the multi-cable has 4 pin connector. This is the only 4 pin connector and therefore it is not identified as the remaining ones. See figure below for illustration.
{|
|[[File:multi_cable_step_motor_crop.jpg|x75px]]
|}
The start button and temperature sensor are directly connected to the DB25 connector, so no need for intermediate connectors.
{|
|[[File:push_button_crop.jpg|x75px]]
|[[File:temp_sensor_2_crop.jpg|x75px]]
|}

===Photo-gate and laser alignment===
The photo-gate and laser alignment can only be performed once the micro-controller has been turned on and it is communicating with a console. See subsection [[#Interface console to micro-controller|Interface console to micro-controller]] on how to power on the micro-controller and how to control the laser.
The alignment consists of pointing the laser into the hole of the photo-gate structure, as shown below in the figure on the left. The laser orientation can be adjusted using the 3 screws from its holding support structure, figure on the middle.

The procedure for the alignment consists of the following:
# Turn on the laser using the "laser on" command
# Verify with the help of a white sheet if the Laser focus dimension is below 1mm by the photo-diode; if not, it as to be adjusted by screwing the laser.
# If necessary, adjust the laser orientation so that its light goes into the photo-gate structure hole (figure on the left). An example of misalignment is shown in the figure on the right.
# Perform the [[#Laser and photo-gate test|Laser and photo-gate test]]
{|
|[[File:Laser_in_photogate_crop.jpg|x200px]]
|[[File:Laser_structure_3_screws_crop.jpg|x200px]]
|[[File:Laser_out_photogate_crop.jpg|x200px]]

|}

===Electric tests===
* Test the micro-switch with the help of a multi-meter (ohmmeter). When released it should present a very high impedance (order of MOhm) and when pressed it should present a very low impedance (like a shunt, ~0 Ohm). Perform the measurement at the micro-switch and at the DB25 pins: between pins no. 3 and 4.
* Check voltage of step-motor power supply to ensure that it is not higher than +12 V.

==dsPic board==
===Overview===
===Schematic===
===Layout===

{|
|[[Precision Pendulum Assembly: Mechanical assembly| Previous Page (Mechanical assembly)]]
|}
{|
|[[Precision Pendulum Assembly: Software management| Next Page (Software management)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Interfaces elétricas | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Interfaces eléctricas | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2022-06-19T22:00:37Z

Ist155317: /* Download firmware file */

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.

__TOC__
=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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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 [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi, open a terminal on the computer and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the [[#RPi Operating System Configuration | RPi Operating System Configuration]]
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to test the port access to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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.
<pre>
sudo crontab -e
</pre>

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.

<pre>
sudo crontab -l
</pre>

=== 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:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not, create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

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

{|
[[Precision Pendulum Assembly: Electrical interfaces | Previous Page (Electrical interfaces)]]
|}
{|
[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]
|}

==Links==

*[[Montagem do Pêndulo de Precisão: Gestão de software | Portuguese Version (Versão em português)]]
*[[Conjunto de péndulo de precisión: Gestión de software | Spanish Version (Versión en español)]]

Precision Pendulum Assembly: Software management

2021-01-24T15:28:34Z

Ist155317: /* Download firmware file */

=Raspberry software=

'''PAGE UNDER CONSTRUCTION'''
== 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 [https://www.raspberrypi.org/downloads/raspbian/ 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 [https://www.raspberrypi.org/documentation/installation/installing-images/README.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
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 [https://en.wikipedia.org/wiki/Secure_Shell 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:
<nowiki>
# 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</nowiki>

Edit the file so it mimics the text shown above. The line:
<nowiki>
static ip_address=123.123.123.123/24</nowiki>
Defines the fallback IP address of the Raspberry Pi when it receives no IP offers through [https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol 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 [https://en.wikipedia.org/wiki/Subnetwork 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, by either taking screenshots of the appropriate dialogs or taking notes, of your Ethernet adapter so you can rollback any changes made.''' Below are some examples for common OSes.

===== Configuring the Ethernet Adapter on Windows 10/8.1/7 and connecting to the RPi =====
*Microsoft provides [https://support.microsoft.com/en-us/help/15089/windows-change-tcp-ip-settings 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 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 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, [https://putty.org/ 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md 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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the '''RPi Operating System Configuration'''
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the '''RPi Operating System Configuration'''
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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 [https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac 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 [https://www.raspberrypi.org/documentation/linux/usage/users.md here]. To connect to the RPi open a terminal on the computer, and write
<nowiki>
ssh pi@RPI ADDRESS</nowiki>
''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
<nowiki>
ssh pi@123.123.123.123</nowiki>
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:
<nowiki>
pi@raspberry:~ $</nowiki>
You have logged in successfully and can now proceed to the '''RPi Operating System Configuration'''
*If there was an error stating
<nowiki>
ssh: connect to host xxx.xxx.xxx.xxx port 22: No route to host</nowiki>
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:

<nowiki>
sudo raspi-config</nowiki>

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 [https://w1.fi/wpa_supplicant/ 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 [https://en.wikipedia.org/wiki/Virtual_Network_Computing ''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 and ''Yes'' when prompted if the serial port hardware should be enabled.

*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, [https://www.raspberrypi.org/documentation/linux/usage/users.md 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''
<nowiki>
sudo useradd newton</nowiki>
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:
<nowiki>
id</nowiki>

The command will output three lists in the format ''number(text)''. Keep the output on screen. Write, but don't execute, the following command:
<nowiki>
sudo usermod -a -G</nowiki>

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:
<nowiki>
sudo usermod -a -G group1,group2,group3,group4 newton</nowiki>

Confirm that the user was successfully added to the system groups by executing:
<nowiki>
id newton</nowiki>

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:
<nowiki>
sudo userdel -remove-home pi</nowiki>

*In order to configure the network where the RPi will be connected, it's often useful to know the [https://en.wikipedia.org/wiki/MAC_address MAC address] of the network adapter. Execute the following command:
<nowiki>
ifconfig</nowiki>

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:
<nowiki>
sudo apt-get update
sudo apt-get full-upgrade</nowiki>

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:
<nowiki>
sudo apt-get install openjdk-8-jre-headless librxtx-java</nowiki>

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:
<pre>
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</pre>

If needed, also install the software for the VPN connection. For example, the openvpn client would be installed by the command:
<pre>
sudo apt-get install openvpn</pre>

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.

=== Network tools ===
The connectivity of the computer were the hardware server will be installed can be tested and verify by installing some tools such as nmap:
<pre>
sudo apt-get install nmap
</pre>
The ''nmap'' program is used to check for the port access testing to elab.ist.utl.pt, elab1.ist.utl.pt and elabmc.ist.utl.pt:
<pre>
nmap -v -A elab.ist.utl.pt
</pre>

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).

==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 HardwareServer will be deployed - in this case, the RPi - and follow these steps:
<ul>
<li>
Validate if the "rec-deployment" directory exists, if not create it by typing: 
<pre>mkdir ${home_directory}/rec-deployment </pre>
<pre>ex: mkdir /home/wpa/rec-deployment </pre>
</li>
<li>
List HardwareServer Zip files: 
<pre>echo "ls *.zip" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist</pre>
</li>
<li>
Once you identified the Hardware Server for your pendulum, copy the hardwareServer Zip file to your machine (Raspberry): 
<pre>echo "get ${hardwareServerZipFile} ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>
<pre>ex. echo "get wpunicvraiHarwareServer_21-02-2020.zip ~/rec-reployment/" | sftp -P2222 wpa@elab1.ist.utl.pt:/dist </pre>

</li>
Go to rec-deployment directory: 
<pre>cd /home/wpa/rec-deployment </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipFile} -d ${hardwareServerAliasName}</pre>
<pre>ex: unzip wpuesciosHardwareServer_24-01-2020.zip -d wpuescios</pre>
</li>
<li>
Change to directory of experience:
<pre>cd ${hardwareServerAliasName}</pre>
<pre>ex: cd wpuescios</pre>
</li>
<li>
Start HardwareServer:
<pre>./Start${AliasName}Driver.sh</pre>
<pre>ex: ./StartwpuesciosDriver.sh</pre>

''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 [https://projects.raspberrypi.org/en/projects/getting-started-with-picamera 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:
<pre>
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</pre>

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:
<pre>
ls /dev
</pre>

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:
<pre>
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 &</pre>

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 | 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 [[List of UDP ports for streaming| 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, [https://en.wikipedia.org/wiki/Session_Description_Protocol| SDP] files must be made available. These can then be independently opened on video player software, like [https://www.videolan.org/vlc/| 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 [[List of UDP ports for streaming| Port listing page.]] The ''HOST'' field should be set to the same value as described on the training sessions.

<pre>
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
</pre>

The SDP file should be created with the same name as indicated on the [[List of UDP ports for streaming| 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:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=== Automatically Start on RPi Boot ===

To make the programs start automatically as the RPi boots, edit the file ''/etc/rc.local'' by executing
<pre>
sudo nano /etc/rc.local
</pre>
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.
<pre>
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 ) &"
</pre>

Note that the HOST and [[List of UDP ports for streaming| 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 ca be used if needed:
<pre>
ln -s /dev/ttyAMA0 /dev/ttyS0
</pre>

=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 [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=DsPic-Raspberry_programmer_interface#Software_use page] for instructions.

==Download firmware file==

The official firmware releases available for download are presented below.

Version 2021_01_96_22_08_46: [[File:Wp 2021 01 06 22 08 46.zip]]

[[Precision Pendulum Assembly: Calibration| Next Page (Calibration)]]

File:Wp 2021 01 06 22 08 46.zip

2021-01-24T15:26:11Z

Ist155317:

World Pendulum

2020-11-21T16:45:52Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance (WPA). This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits*
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}
<nowiki>*</nowiki>These limits were estimated for the standard World Pendulum Alliance launcher (WPA). A photo of a standard WPA launcher is shown on the figure on the right.
Check [http://www.elab.tecnico.ulisboa.pt/wiki/index.php?title=Precision_Pendulum_Assembly:_Apparatus_description#Pendulum_length_limits Pendulum length limits] to understand how these limits were obtained.

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:44:37Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance (WPA). This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits*
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}
<nowiki>*</nowiki>These limits were estimated for the standard World Pendulum Alliance launcher (WPA). A photo of a standard WPA launcher is shown on the figure on the right.
Check [[#Pendulum length limits|Pendulum length limits]] to understand how these limits were obtained.

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:43:54Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance (WPA). This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits*
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}
<nowiki>*</nowiki>These limits were estimated for the standard World Pendulum Alliance launcher (WPA). A photo of a standard WPA launcher is shown on the figure on the right.
Check [[#Pendulum length limits|Pendulum length limits]] to understand these limits were obtained.

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:42:00Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance (WPA). This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits*
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}
*These limits were estimated for the standard World Pendulum Alliance launcher (WPA). A photo of a standard WPA launcher is shown on the figure on the right.
Check [[#Pendulum length limits|Pendulum length limits]] to understand these limits were obtained.

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:38:36Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance (WPA). This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits for standard WPA launcher (see figure on the right for WPA launcher see [[#Pendulum length limits|Pendulum length limits]] to understand these limits)
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:35:47Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]
[[File:Launcher_2.png|thumb|Standard launcher of the pendulum mass for the World Pendulum Alliance. This launcher uses a V-slot rail technology and it is characterized by a maximum horizontal launching distance of 250 mm.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits for standard WPA launcher (see [[#Pendulum length limits|Pendulum length limits]] to understand these limits)
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]

World Pendulum

2020-11-21T16:33:11Z

Ist155317: /* Experimental apparatus */

=Description=
[[File:Soyuz VS03 liftoff.jpg||thumb|Soyuz lift-off from French Guiana @ 5º north of the Equator .|right|border|236px]]
Rockets are launched to space from equatorial latitudes. This is due to the fact that the apparent weight of objects is gradually reduced from the poles to the equator. We will feel lighter at the equator than at the poles!

This small difference in apparent weight allows the same rocket to launch heavier payloads into orbit if launched nearer from the equator. For example, a Soyuz rocket launching into geostationary orbit from the French Guiana (5ºN) can carry 3 tons while it will only be capable of launching 1.7 tons of cargo when launched from Baikonur, Kazakhstan (46ºN).

The goal of this experiment is to find the value of the gravity "constant" through a constellation of pendulums placed in various latitudes and remotely operated, through the internet, by anyone.

It is expected that CPLP countries can contribute to this effort, bringing students, teachers and interested citizens closer together.

There are two different activities occurring simultaneously: (i) access, through e-lab, of the pendulums located in different latitudes and (ii) the construction and local operation in schools or at home.

Lisboa, Ilhéus, Faro e Rio de Janeiro were the first cities to contribute to the network in January 2013, making it possible for the first fits of experimental data to the theoretical equation within our project that describes how gravity changes with latitude to occur.

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

<div class="toccolours mw-collapsible mw-collapsed" style="width:420px">
'''Links'''
<div class="mw-collapsible-content">

*Video Faro: rtsp://elabmc.ist.utl.pt/worldpendulum_ccvalg.sdp
*Video Lisboa: rtsp://elabmc.ist.utl.pt/worldpendulum_planetarium.sdp
*Video Ilhéus: rtsp://elabmc.ist.utl.pt/worldpendulum_ilheus.sdp
*Video Rio Janeiro: rtsp://elabmc.ist.utl.pt/worldpendulum_puc.sdp
*Video Maputo: rtsp://elabmc.ist.utl.pt/worldpendulum_maputo.sdp
*Video São Tomé: rtsp://elabmc.ist.utl.pt/wp_saotome.sdp
*Laboratory: World Pendulum in [http://elab.ist.utl.pt elab.ist.utl.pt]
*Control room: Choose a location
*Grade: *

</div>
</div>

==Who likes this idea==

[[File:PBA B1 1.png|border|180px|border|180px]]
[[File:LogoSPF long.jpg|border|180px]]
[[File:logo_EPS_blue.gif|border|80px]]
[[File:Logo mar.png|border|80px]]
[[File:LogoPlanetarioGulbenkian.png|border|180px]]
[[File:LogoCCVALG.png|border|204px|border|180px]]
[[File:LogoPlanetarioRioJaneiro.png|border|180px]]
[[File:Logo info tech.png|border|180px]]
[[File:Logo_tap.png|border|180px]]
[[File:Cenfim Logo.jpg|border|180px]]
[[File:LogoPUC.PNG|border|60px]]
[[File:UESC BRASÃO ref.jpg|border|60px]]
[[File:UFRPE.jpg|border|60px]]
[[File:Logo_DGAE.png|border|380px]]
[[File:LogosBeneficairesErasmus+RIGHT EN.jpg|border|280px]]

=Experimental apparatus=
The pendulum design used was based in Dr. Jodl's design<ref name="jodl">World pendulum—a distributed remotely controlled laboratory (RCL) to measure the Earth's gravitational acceleration depending on geographical latitude, Grober S, Vetter M, Eckert B and Jodl H J, European Journal of Physics - EUR J PHYS , vol. 28, no. 3, pp. 603-613, 2007</ref>. Some minor changes were made to allow the same design to be easily replicated in high schools. The data concerning each pendulum follows:

[[File:WordlPendulum.JPG|thumb|Pendulum used for the world pendulum standard gravity experiment.]]
[[File:Stringsuport.png|thumb|Pendulum string support to avoid elongation errors. The cable is fixed by soldering it into a brass M4 screw 40mm long.]]

{| class="wikitable"
!colspan="6"|Physical sizes by place
|-
| Place
| Latitude
| Longitude
| Altitude (m)
| Cable length (mm)
| Sphere diameter (mm)
|-
| CCV_Algarve/Faro
| 37º00'N
| 7º56'W
| 10
| 2677 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| UESC/Ilhéus
| 14º47'S
| 39º10'W
| 220
| 2705 +/- 0.5 @23ºC
| 80.5 +/- 1.0
|-
| Lisbon
| 38º41'N
| 9º12'W
| 20
| 2677 +/- 0.5 @19ºC
| 80.5 +/- 1.0
|-
| Maputo
| 25º56'S
| 32º36'E
| 80
| 2609.8 +/- 0.5 @27ºC
| 80.5 +/- 1.0
|-
| São Tomé
| 0º21'N
| 6º43'E
| 50
| 2756.5 +/- 0.5 @29ºC
| 81.8 +/- 0.5
|-
| Prague - CTU
| 50º5.5'N
| 14º25.0'E
| 150
| 2850 +/- 0.5 @25ºC
| 80.1 +/- 0.5
|-
| Barcelona - UPC
| 41º24.6'N
| 2º13.1'E
| 55
| 2756.5 +/- 0.5
| 81.8 +/- 0.1
|-
| Rio de Janeiro - PUC
| 22º54.1'S
| 43º12'W
| 50
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Praia - UniCV
| 14°56'N
| 23°31'W
| 40
| 2826,0 +/- 0.5
| 81.6 +/- 0.1
|-
| Bogotá - UniAndes
| 4°36'N
| 74°3'W
| 2650
| 2815,3 +/- 0.5
| 82.0 +/- 0.1
|-
| Panama city - UTP
| 9°1.3'N
| 79°31.9'W
| 82
| 2825 + /- 0.5 @28ºC
| 81.9 +/- 0.1
|-
| Santiago - UChile
| 33°27.5'S
| 70°39.8'W
| 552
| 2825 +/- 0.5 @27ºC
| 81.9 +/- 0.1
|-
| Valparaiso - UTFSM
| 33°1'S
| 71°37'W
| 30
| 2827.5 +/- 0.5 @28ºC
| 81.8 +/- 0.1
|-
| Panama city - USMA
| 33°1'S
| 71°37'W
| 30
| 2800.0 +/- 0.5 @35ºC
| 81.8 +/- 0.1
|-
| Brasilia - UnB
| 15° 46'S
| 47° 52'W
| 1034
| 2826.8 mm +/- 0.5 @26ºC
| 81.4 +/- 0.1
|-
| Marseille - ECM
| 43°20.6'N
| 5°26.2'E
| 162
| 2811.0 mm +/- 0.5 @22ºC
| 82.0 +/- 0.1
|}

{| class="wikitable"
!colspan="2"|Typical quantities
|-
| String length (not counting the sphere) || min: 0.5 m nominal: 2.8m max: 12m
|-
| Sphere mass || 2kg +/- 75g
|-
| Sphere diameter || 81.2mm +/-1.5mm
|-
| String || Remanium(r) - Stainless steel (Nickel chromium)
- 0,4mm
|-
| Modulus of elasticity of string || ~200GPa
|-
| Oscillation period measurement system || Microprocessor with 7,3728MHz - 30ppm crystal
+ laser + PIN photodiode
|-
| Wire CTE (25-500ºC) (Coefficient of thermal expansion) || ~14 x 10-6 K-1
|}

{| class="wikitable"
!colspan="2"|Penulum length limits for standard WPA launcher (see [[#Pendulum length limits|Pendulum length limits]] to understand these limits)
|-
| Minimum || ~1.5 m
|-
| Maximum || virtually no limit (~63.5 m)
|}

The experimental apparatus can be easily adapted to human operation, using a good chronometer, for local execution. The stainless steel structures can made in by brass or bronze for easier machining. The cable used can be replaced by a sport fishing steel cable and the mass can be replaced by a Olympic weight throw training weight, weighing 2Kg. A calibrated measuring tape should be used to measure the cable length, '''a few days after assembling the apparatus to allow for cable expansion'''.

=Local partners=
The pendulum<ref name="serway">Physics for scientists and engineers, 5th edition, Hardcourt College Publishers, R.Serway and R. Beichner, 2000</ref>, although one of the simplest systems commonly studied, is one of the richest in terms of physics.

In order to build a precise pendulum the most important factors are the precise measurement of the length of the cable, its quality, and of that of the pendulum supports. Selecting a mass between 1 to 4 Kg ensures that the pendulum's period error will be small enough for small local gravity changes (smaller than 0.1%) to be detectable, as long as a precise chronometer is used for timekeeping.

A local apparatus can be assembled using readily available materials and the local "g" values determined using such an apparatus can then be compared to the ones obtained through the remote pendulum constellation and the theoretical model.

Collecting this data through a social network will allow a more precise description of how "g" varies around the globe. The "World Pendulum" can be an important collaborative network for the dissemination of physics in schools.

Instructions on how to build such a pendulum are available in [[Precision Pendulum]].
The documentation of the development and construction of a pendulum are available in [[Precision Pendulum]] while the instructions on how to assemble it are available in [[Precision Pendulum Assembly]].

If you want to be a part of the World Pendulum network, please contact us by sending us an [mailto:wwwelab@ist.utl.pt email].

=Physics=
Determining gravity's acceleration in different parts of the globe raises questions about the importance of models in physics. It's possible to show that gravity's acceleration at sea level changes with latitude, and therefore a correction is needed for each individual location. This process allows us to demystify science and correct the existing "urban myth" around some physical constants that only are truly constant when some approximations are done. In this particular case, we will show how the introduction of successive corrections to gravity's "constant" will lead to values closer to those experimentally obtained.

==Geophysical model==
The starting point is the commonly used, constant, value of 9.81 ms-2. This is obtained by considering the Earth as being (i) a sphere (ii) that is not rotating. It's trivial to note that this model, due to the symmetry of the spherical form, does not allow for different values in different locations. This changes as soon as Earth's rotation dynamics and ellipsoid shape (flattening of the poles) are taken in account. These factors allow for gravity to change with latitude, and in fact these two factors are the two most important ones in this phenomena, outweighing every other effect, such as (i) altitude, (ii) tidal forces, and (iii) subsoil composition.

To demonstrate these finer aspects, gravity's acceleration must be determined in various latitudes around the globe distant from each other. Using the data collected, students can then ask themselves about how "constant" the value truly is and improve their intuition of gravity.

===Experimental studies===
====Variation with latitude====
As seen, the first possible study consists of using the remote pendulums to obtain a measurement of the local gravity acceleration for each location they're based in. Through considering (or not) several factors, it is possible to fit the data to a experimental description of the Earth using spherical harmonics (equation \eqref{harmonica-esferica}). This experimental work can be conducted using e-lab's pendulum constellation and [http://rcl-munich.informatik.unibw-muenchen.de/ our partner's pendulums].

====Local determination====
Following the instructions available in this wiki - [[Precision_Pendulum]] - or using any other kind of design that results in a rigorous apparatus, a local pendulum is built. It's then possible for measurements of local gravity to be made, as long as a good chronometer is used. Furthermore, it's also possible to contribute to the enrichment of the World Pendulum network's [https://docs.google.com/a/kic-innoenergy.com/spreadsheet/ccc?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE#gid=0 spreadsheet].

====[[Tidal study]]====
Using an almanac appropriate for the location, on can obtain the times of particular Moon/Sun alignments (full moon, new moon, waxing crescent and waxing gibbous). Plotting a graph spanning several months, one can try to verify and quantify the influence of tidal forces and Moon/Sun alignments in the apparent weight. It's possible to try and verify the correlation between Moon phases and changes in measurement of local gravity, by making a month or year-long study.
Tidal effects are on the limit of detection by the pendulums of the e-lab constellation. For the experiment to be successful, it's necessary to be very rigorous on the time at which the experimental runs are made and some advanced numerical techniques, like the Fourier transform, need to by employed for the signal to be extracted from the data.

====Analysis of wire torsion ====
[[File:Torcao.jpg||thumb|Effect of wire torsion and sphere ellipticity in the measurement of pendulum speed.|right|border|240px]]
Those paying more attention will note that the speed of the mass changes due to wire torsion and due to the mass not being a perfect sphere. This is pictured in the image to the right. The pendulum can be studied taking into account the effect of the wire torsion (the use of Euler-Lagrange equations is recommended for this).

==Uniformly accelerated circular movement==
The speed of the sphere in the lowest point of the trajectory is determined by measuring how much time the laser beam is interrupted. Knowing the sphere diameter, it's trivial to determine the speed at the origin. From this, the maximum kinetic energy can be calculated and the launching height of the pendulum determined. The calculated launching point can then be compared with the real one.

=Latitude provideres=

[[file:G_latitude.png|link=https://docs.google.com/a/kic-innoenergy.com/spreadsheet/oimg?key=0AkxMmuJA92wgdHZnWHk5WHhaQldINGFqSTl6OGdpSlE&oid=1&zx=hfmrs4egtbuf|thumb|The gravitational constant plotted against latitude with points of interest around the globe highlighted. Principe Island is just over zero latitude. Lisbon value was obtained with the current experiment and already over plotted on the graphic.]]

Language is an important nationality factor ("My fatherland is the Portuguese language.", F. Pessoa) and a simple way to define what is called brother countries ("países irmãos"). Only four languages are disseminated around the world, Portuguese being one of them. The Portuguese speaking community covers latitudes from ~30S to ~40N, almost a 75º span across the equator. Therefore, CPLP countries can help by being "latitude providers" (see Figure).

To conduct this world experiment, at least four spaced points are needed in order to have a proper fit. But due to the strong non-linearity of the equation, more points are needed to provide a suitable adjustment, in particular on the "knee" close to the earth’s equator. Brazil itself can provide almost four crucial points close to the equator (e.g. Recife 8º, Salvador – 12º, Rio de Janeiro – 23º, Porto Alegre – 30º) but lacks points with a latitude where the characteristic varies more strongly, the almost linear region around 30º to 60º, where Portugal can give two good points (e.g. Porto - 37º and Faro - 41º). Mozambique can contribute with 27º (Maputo) and S. Tomé e Principe or Brazil are both good choices to cover the equator. Angola could give complementary points to those acquired in Brazil, as the sensibility of the measurement is more pronounced close to the equator and the poles.

=Data fitting=
Available references <ref name="serway"></ref> <ref name="rcl">http://rcl-munich.informatik.unibw-muenchen.de/</ref> <ref name="olsom">Nelson, Robert; M. G. Olsson (February 1987). "The pendulum - Rich physics from a simple system". American Journal of Physics 54 (2):
doi:10.1119/1.14703</ref> <ref name="gauld">Pendulums in the Physics Education Literature: A Bibliography, Gauld, Colin 2004 Science & Education, issue 7, volume 13, 811-832
(http://dx.doi.org/10.1007/s11191-004-9508-7)</ref> <ref name="qureshi">The exact equation of motion of a simple pendulum of arbitrary amplitude: a hypergeometric approach, M I Qureshi et al 2010 Eur. J. Phys. 31 1485(http://dx.doi.org/10.1088/0143-0807/31/6/014)</ref> <ref name="ochs"> A comprehensive analytical solution of the nonlinear pendulum, Karlheinz Ochs 2011 Eur. J. Phys. 32 479 (http://dx.doi.org/10.1088/0143-0807/32/2/019)</ref> give a very good description of the mathematical model needed to fit the data. If all major factors are taken into account, gravity as a function of latitude is given by:

<math>
g_{n}(\varphi) = 9.780 326 772\times[1 + 0.005 302 33 \cdot sin^{2}(\varphi) - 0.000 005 89 \cdot sin^{2}(2\varphi)]
</math>

where $\varphi$ is the latitude. This expression is one of the best experimental approximations and results from the standardization agreement to adjust the World Geodetic System datum surface (WSG84) to an ellipsoid with radius r1=6378137m at the equator and r2=6356752m polar semi-minor radius.
This formula takes into account the fact that the Earth is an ellipsoid and that there is an additional increase in the acceleration of gravity when one moves nearer to the poles, due to a weaker centrifugal force. Nevertheless the students could derive a non-harmonic, first order approximation by taking into account only centrifugal force. Then, as a second step, they could include the two other major errors, the centrifugal force and earth’s ellipsoid format.

[[File:Period_over_time.png|thumb|The variability of the period with elapsed time (angle amplitude < 7,5º), showing that this error is less than 0,05% regardless initial amplitude.]]

The pictures shows the expected deviation from the “earth’s constant acceleration”, the real acceleration for each latitude. We have plotted the point already obtained with this apparatus in Lisbon and the marks over the expected latitudes for future partners.
Of course these approximations do not include one important source of deviation from real data to the mathematical model, the experimental error, as we do not include the experimental source of error. However, those systematic errors could be under the expected precision needed (0,1%) for the former approximation if a careful design of the apparatus is considered. Nevertheless those errors must be discussed in advanced courses and their weight must be proved when considering the real pendulum.

=Historical notes=
The pendulum importance as the basis of clocks and chronographs was only overthrown when the Royal Society convinced the English parliament to create an award, ranging from 10k£ to 20k£ (equivalent nowadays to more than 3.5M€), for the invention of a chronograph that didn't depend on it. The time precision of pendulum based systems is only bettered by modern electronic systems.

In the discovery age longitude was determined with a high error, since clocks and chronographs were reliant on pendulums and these were very sensitive to ships rocking, suffering changes in frequency or even stopping. Local longitude was calculated by comparing the solar hour (or stellar hour) with the ship's clock time.

=References=

<references />

=Links=
*[[Pêndulo Mundial | Portuguese version (Versão em Português)]]
*[[Péndulo mundial| Spanish version (Versión en español)]]
*[https://www.youtube.com/watch?v=ZOOFw_Nlee8&feature=youtu.be Building your own pendulum]