=dsPic-Raspberry programmer interface=

A general purpose interface consisting in two opto-couplers have been developed to program the dsPic micro-controllers directly from the Raspberry, allowing remote maintenance and reprogramming of each de-localized unit.

It as to be powered by 12 V (minimum voltage 10.5V - maximum voltage 13.5V) dsPic node unregulated Vcc and feed by the Raspberry GP_I/O, with a common digital ground.

== Pin-out and connections==
[[File:ProgrammerOptoCouplerTopView.jpg||thumb|Photo of the pic programmer.|right|border|180px]]
[[File:SchematicPicProgrammer.png||thumb|Photo of the pic programmer.|right|border|180px]]

The following table describes the pin-out assembly of the opt-programmer developed to be used with picpgm software.

{| class="wikitable"
!colspan="6"|Programmer pin-out
|-
| '''Rasp I/O
| '''Label
| '''Programmer I/O
| '''Picpgm function (invert)
| '''Cable
|-
| 39
| GND
| GND
| -
| Blue/Wh
|-
| 37
| BCM26
| PGD1//470
| DIN (0)
| Brown
|-
| 35
| BCM19
| PGD2//470
| DOUT (0)
| Blue
|-
| 33
| BCM13
| PGC
| CLK (0)
| Green
|-
| 29
| BCM5
| RST (when high)
| MCLR (1)
| Brown/Wh
|-
| 03
| BCM2
| PGMmode (high)
| PGM (0)
| Orange
|}

If RST low and PGMmode high the pic enter program mode (12V @ MCLR).
If RST high (PGMmode any but should be low) the pic reset and hold.
If PGMmode low and RST low the pic run with MCLR at high impedance (or pulled up from dsPicnode side.

PGD1 and PDG2 are summed with two 470 ohm resistors to the pic PGD
PGC is connected to the pic PGC with one series resistor of 470 ohm.

The 12V pull-up is wired with a 100 Ohm resistor (version 1) and 470 ohm (original version). This is a non-essential situation as it was devised to create 4.3V if PGMmode and RST were independent.

The Picpgm column shows how to set the Picpgm configuration file in order to use this programmer with the GPIO's shown on the table. It also shows if the invert option should be selected for each of them.

==Software use==

The picpgm software is [http://picpgm.picprojects.net/index.html hosted here] and should be used with the following script:

 Bash file @ /etc/rc.local 
<pre>
#The following lines should be added to file to allow the pic to run after RPI boot
#The wiringpi package needs to be installed
gpio -g mode 5 down
gpio -g mode 2 down
</pre>

A backup is also founded at elab1/...

2020-02-21T17:25:08Z

Ist176128: /* Video Streaming */

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

==Autonomous codes==

=== Hardware Server ===

Open terminal on HardwareServer machine (in this case RPi) and folow the procedure:
<ul>
<li>
Validate if rec-deployement directory exits, if not create by typing: 
<pre>mkdir ${home_directory}/rec-deployement </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipLocation}/${hardwareServerZipFile} -d ${home_directory}/rec-deployement/${hardwareServerAliasName}</pre>
</li>
<li>
Start HardwareServer:
<pre>cd ${home_directory}/rec-deployement/${hardwareServerAliasName} && ./Start${AliasName}Driver.sh</pre>
</li>

''NOTE''

The HardwareServer should only be deploy after the complete calibration procedure described on the next page.

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

*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 its almost the case that it is, 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>

[[List of UDP ports for streaming| Port listing]]

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

Precision Pendulum Assembly: Software management

2020-02-21T17:24:37Z

Ist176128:

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

==Autonomous codes==

=== Hardware Server ===

Open terminal on HardwareServer machine (in this case RPi) and folow the procedure:
<ul>
<li>
Validate if rec-deployement directory exits, if not create by typing: 
<pre>mkdir ${home_directory}/rec-deployement </pre>
</li>
<li>
Unzip HardwareServer's zip file to rec-deployment directory
<pre>unzip ${hardwareServerZipLocation}/${hardwareServerZipFile} -d ${home_directory}/rec-deployement/${hardwareServerAliasName}</pre>
</li>
<li>
Start HardwareServer:
<pre>cd ${home_directory}/rec-deployement/${hardwareServerAliasName} && ./Start${AliasName}Driver.sh</pre>
</li>

''NOTE''

The HardwareServer should only be deploy after the complete calibration procedure described on the next page.

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

*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 its almost the case that it is, 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>

[[List of UDP ports for streaming| Port listing]]

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