Merge branch 'icub-tech-iit:master' into master

docs/ergocub_operating_systems/ergocub_torso/install_from_scratch.md

@@ -0,0 +1,15 @@
+# Install from scratch
+
+`ergocub-torso` is based on Ubuntu server 22.04, we will install it from the default installer and then we manually customize it.
+
+To install the OS from scratch, please follow [this guide](../../icub_operating_systems/icubos/installation-from-scratch.md), being careful to install the [**Ubuntu 22.04 LTS Server**](https://releases.ubuntu.com/focal).
+
+!!! note
+    Remember to substitute the references to **`icub`** and  **`icub-head`** respectively with **`ergocub`** and **`ergocub-torso`**.
+
+To synchronize the system date and time, edit the file `/etc/default/ntpdate` by changing the following lines:
+
+```
+NTPDATE_USE_NTP_CONF="no"
+NTPSERVERS="10.0.2.1 ntp.ubuntu.com"
+```

docs/ergocub_operating_systems/index.md

@@ -0,0 +1,14 @@
+# Introduction
+
+This manual describes how to install and customize the linux operating systems required to run on machines in the ergoCub enviroment. 
+
+The ergoCub robot relies on two machines: `ergocub-head`, a [`NVIDIA Jetson Xavier AGX`](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-xavier-series/) used to control the realsense camera, the lidar and the OLED display, and `ergocub-torso`, which is a [`COM express type 10`](https://www.advantech.com/en-eu/products/0a009637-4f9d-4541-8624-a55de3ffb2a6/som-7583/mod_17ca9251-bdf5-4f74-9256-edd63a373b39) that controls the motors.
+
+# OS configurations
+
+The following guides will help you to properly configure the OS for the specific board.
+
+- [ergocub-head](../icub_operating_systems/icubos/jetpack.md)
+- [ergocub-torso](ergocub_torso/install_from_scratch.md)
+
+Alternatively, you can download the OS pre-built images [here](../icub_operating_systems/download.md).

docs/ergocub_operating_systems/network.md

@@ -0,0 +1,64 @@
+# ergoCub network
+
+The network on ergocub can be divided in two parts:
+
+- **internal network (10.0.1.0/24)**: it connects `ergocub-torso` to all the motor controller boards on the robot, it is a segregated network (there is no connection from the nodes on its subnet and the ouside world) and it is used to send motor commands from ergocub-torso to motor control boards;
+- **extenal network (10.0.2.0/24)**: it is managed by the ergocub-server and it connects all the ergoCub machines together, handling the internet connection too. This connection can be _wired_ or _wireless_;
+- **backup network (10.0.0.0/24)**: this is a backup/troubleshoot network for connecting directly to the robot in case of not reaching the external network.
+
+
+## ergoCub network interfaces
+
+- `ergocub-torso`
+
+    On ergocub-torso, one of the two ethernet interfaces is connected to the internal network. The other one, instead, is directly connected to ergocub-head via backup network.
+
+- `ergocub-head`
+
+    On ergocub-head, the ethernet interfaces are bridged together on the backup network.
+
+Both head and torso are connected to the external network via WiFi.
+
+## IP addresses and other network configurations
+
+Below you can find the default network parameters of the ergoCub networks.
+
+### Internal network configurations
+
+This configuration depends deeply on the motor control board firmware and thus it can't be changed.
+
+- **IP address** : 10.0.1.104 - _STATIC_
+- **Netmask** : 255.255.255.0
+
+Since this is a segregated network, there is no default gateway.
+
+### External network configurations
+
+Usually, it is a static configuration, but it works also in DHCP mode. This configuration _can be changed_ but it is not recommended.
+
+For `ergocub-torso`:
+
+- **WiFi IP address** : 10.0.2.2
+- **Netmask** : 255.255.255.0
+- **Default Gateway** : 10.0.2.1
+- **DNS server** : 10.0.2.1
+
+For `ergocub-head`:
+
+- **WiFi IP address** : 10.0.2.3
+- **Netmask** : 255.255.255.0
+- **Default Gateway** : 10.0.2.1
+- **DNS server** : 10.0.2.1
+
+### Backup network configurations
+
+For `ergocub-torso`:
+
+- **IP address** : 10.0.0.2
+- **Netmask** : 255.255.255.0
+
+For `ergocub-head`:
+
+- **IP address** : 10.0.0.3
+- **Netmask** : 255.255.255.0
+

docs/icub_firmware/canLoader/canLoader.md

@@ -27,7 +27,7 @@ The device type is the software module that wraps the can bus device you are usi
 ## Standard firmware update (DSP)
 The firmware upgrade of the whole robot is performed using a script based on a command line version of the [CanLoader](../canLoader/canLoader.md) module. Before you try to use this script please check that this module is compiled on the pc104. You should also make sure that the hardware modules it needs (controlboard, canmotioncontrol, ecan/pcan/cfw2can) are compiled and liked correctly (this is usually the case on the robot pc104).
 
-Please notice that the firmware upgrade is delicate procedure which changes one of the core parts of the iCub robot software (and therefore requires a corresponding update of the yarp and iCub modules). If you decide to perform a firmware upgrade, be aware that this might change the robot motor behaviour quite a lot. Nevertheless, a firmware upgrade is always recommended because it usually corresponds to improvements in the control board performances. Finally, remember to perform the firmware update with your robot in a 'clean' state (i.e. control boards have been just turned on, and iCubinterface has not run yet).
+Please, notice that the firmware upgrade is delicate procedure which changes one of the core parts of the iCub robot software (and therefore requires a corresponding update of the yarp and iCub modules). If you decide to perform a firmware upgrade, be aware that this might change the robot motor behaviour quite a lot. Nevertheless, a firmware upgrade is always recommended because it usually corresponds to improvements in the control board performances. Finally, remember to perform the firmware update with your robot in a 'clean' state (i.e. control boards have been just turned on, and iCubinterface has not run yet).
 
 Here are the steps to perform the firmware update:
 
@@ -56,7 +56,7 @@ The .txt file simply contains a list of board addresses and associated firmware
 
 where:
 
-- canModule can be either pcan (if you are using the PLX custom board) or ecan (if you are using the commercial usb to can interface produced by [ESD](http://www.esd-electronics.com/)) or cfw2can (if you are using the custom CFW2 board).
+- canModule can be either pcan (if you are using the PLX custom board) or ecan (if you are using the commercial usb to can interface produced by [ESD](https://esd.eu/) or cfw2can (if you are using the custom CFW2 board).
 - canDeviceNum is the CAN line identifier (i.e: 0 for the head, 1 for the left arm, 2 for the right arm, etc..)
 - boardID is the board address (0...14) on the selected CAN line.
 - firmware is the firmware binary file (*.s for motorola-based boards, *.hex for DSPIC-based board)

docs/icub_operating_systems/icubos/installation-from-scratch.md

@@ -1,6 +1,6 @@
 # The OS on icub-head - Installation from scratch
 
-Since iCubOS is based on the Ubuntu server, we will install it from the default installer and then manually customize it.
+Since iCubOS is based on the Ubuntu server, we will install the latter from the default installer and then manually customize it.
 
 ## Latest versions
 
@@ -40,7 +40,7 @@ Install the system by choosing the default options, except for the following ste
 #### Identity
 
 - **Your name** : `icub`
-- **Your Server's name** : `icub-head'
+- **Your Server's name** : `icub-head`
 - **Pick a username** : `icub`
 - **Choose a password** : `icub`
 

docs/icub_operating_systems/icubos/jetpack.md

@@ -1,15 +1,16 @@
 # The NVIDIA JetPack - Introduction
 
-This guide is intended for a developer that wants to flash and setup the Nvidia Jetson Xavier board for the iCub head.
-The unit uses a [ConnectTech carrier board](https://connecttech.com/product/quark-carrier-nvidia-jetson-xavier-nx/), so the preliminary instructions will be focused on that specific hardware.
+This guide is intended for developers who want to flash and set up the [Nvidia Jetson Xavier boards](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-xavier-series/) (i.e., AXG, NX).
+
+These units use a ConnectTech carrier board ([Quark](https://connecttech.com/product/quark-carrier-nvidia-jetson-xavier-nx/) for the Xavier NX, [Rogue](https://connecttech.com/product/rogue-carrier-nvidia-jetson-agx-xavier/) for the AGX), so the preliminary instructions will be focused on that specific hardware.
 
 # Requirements
 
 ## Hardware
 - x86 PC/laptop for downloading Jetpack and flashing the OS
 - USB-C to USB-A (or USB-C to USB-C) cable to connect the PC to the ConnecTech carrier
 - Power supply cable
-- Bench/System/ATE programmable DC power supply, capable of supplying 20V / 2A
+- Bench/System/ATE programmable DC power supply, capable of supplying 20V/2A
 - (optional) Ethernet cable to connect the Xavier to access it with SSH
 
 To use the Xavier directly without SSHing into it:
@@ -23,8 +24,7 @@ On the developer's host PC:
 - Nvidia JetPack installed through SDK Manager (instructions below)
 - Xavier [Connecttech BSP](https://connecttech.com/product/quark-carrier-nvidia-jetson-xavier-nx/) for the `board_type` board (e.g. AGX, NX) and JetPack `jetpack_ver`(e.g 4.4.2, 5.0.2). (Not required if you already have the image ready to flash)
 
-
-# Intructions
+# Instructions
 
 ## Carrier hardware configuration
 Make sure that the switches on the carrier are set like in the picture below, so that the unit can boot manually when pressing the power (PWR) button. DO NOT power on the unit until instructed.
@@ -33,10 +33,10 @@ Make sure that the switches on the carrier are set like in the picture below, so
 
 
 ## Hardware connection
-1. Connect the carrier to the power supply through the provided cable, and set the power supply to 16V / 2A
+1. Connect the carrier to the power supply through the provided cable, and set the power supply to 16V/2A.
 2. Keep the power supply OFF.
 3. Connect the HDMI cable, and the mouse/keyboard to the carrier.
-4. Use the USB-C cable to connect the PC to the OTG USB port on the carrier
+4. Use the USB-C cable to connect the PC to the OTG USB port on the carrier.
 
 ![](../img/usbotg.jpg)
 
@@ -48,31 +48,33 @@ If you need to install an new JetPack image from scratch please follow the follo
 
 ### Jetpack setup on the host
 1. Download the Nvidia SDK manager from the [official website](https://developer.nvidia.com/embedded/jetpack) by clicking *Download Nvidia SDK Manager*
-
 2. Run SDKManager and login with developer.nvidia.com credentials, and follow these steps:
    1. Set the following options:
       - Target Hardware: Jetson Xavier `board_type`
       - Target operating system: *Linux Jetpack `jetpack_ver`*.
    2. Check that everything is selected and continue
-   3. The SDKManager will ask the user password to download all the components and it will install them into a local folder on the host (~12Gb of free space required); Remember, this is the password of the local Ubuntu host, not the Jetson Xavier.
-   4.  After the installation, the SDK Manager will be ready to flash the OS image on the Xavier; **Do not preceed further!** Press SKIP to abort the operation and quit from the SDK Manager
-3. Download the ConnectTech board support package from the [official website](https://connecttech.com/product/quark-carrier-nvidia-jetson-xavier-nx/): under Downloads click on the bsp you need, it will be downloaded as `.tgz` archive.
-4. At this point the `sdkManager` should have created a folder tree in `~/nvidia` containing all the files needed for the flash. Copy the `.tgz` package downloaded from Connectech website into `~/nvidia/nvidia_sdk/JetPack_<jetpack_ver>_Linux_<board_type>/Linux_for_Tegra/`
+   3. The SDKManager will ask the user password to download all the components and it will install them into a local folder on the host (~12Gb of free space required); remember: this is the password of the local Ubuntu host, not the Jetson Xavier.
+   4. After the installation, the SDK Manager will be ready to flash the OS image on the Xavier; **Do not preceed further!** Press SKIP to abort the operation and quit from the SDK Manager
+3. Download the ConnectTech board support package from the [official website](https://connecttech.com/product/quark-carrier-nvidia-jetson-xavier-nx/): under Downloads click on the BSP you need, it will be downloaded as `.tgz` archive.
+4. At this point the `sdkManager` should have created a folder tree in `~/nvidia` containing all the files needed for the flash. Copy the `.tgz` package downloaded from ConnectTech website into `~/nvidia/nvidia_sdk/JetPack_<jetpack_ver>_Linux_<board_type>/Linux_for_Tegra/`
 5. Extract the BSP: `tar -xzf CTI-<*>.tgz`
 
 Before flashing the image, we need first to put the board in recovery mode.
 
 
 ### Booting the Xavier in Recovery mode
 
-With the Nvidia Jetson Xavier AGX:
+With the **Nvidia Jetson Xavier AGX**:
+
 1. Press the Force Recovery (FR) button on the carrier and keep it pressed
 2. Turn on the power supply (16V)
 3. Wait for several seconds, keeping the FR button pressed
 4. Press the power (PWR) button for at least one second. Wait for several seconds
-5. Release the FR button. Now the board is programming mode
+5. Release the FR button.
+
+Now the board is programming mode.
 
-With a Nvidia Jetson Xavier NX, instead, keep the button RST/RECOVERY pressed for several seconds and then, when released, the board will be in recovery mode.
+With a **Nvidia Jetson Xavier NX**, instead, keep the button RST/RECOVERY pressed for several seconds and then, when released, the board will be in recovery mode.
 
 In order to check that the board went in recovery mode, run on a terminal in the host
 
@@ -92,7 +94,7 @@ At this point we are ready to flash, in the host:
 1. Change into the CTI-L4T directory: `cd ./CTI-L4T`
 2. Run the install script (as root or sudo) to automatically install the BSP files to the correct locations: `sudo ./install.sh`
 
-[Here](https://connecttech.com/resource-center/kdb373/) you can find the tutorial about the procedure by Connecttech.
+[Here](https://connecttech.com/resource-center/kdb373/) you can find the tutorial about the procedure by ConnectTech.
 
 
 ### Verify the installation
@@ -103,11 +105,12 @@ After configuring the system, the Xavier should boot normally and be ready to us
 
 #### Complete the OEM installation
 After booting into the OS, follow the OEM installation with the following options:
+
 1. Accept the license agreement
 2. Select English language
 3. Select the English (US) keyboard layout
 4. Select the preferred time zone
-5. User the user name `icub` with the hostname `icub-head-cam`
+5. Set the user name to `icub` with the hostname `icub-head-cam` or `ergocub` with hostname `ergocub-head`, depending on the robot the board will be mounted on
 6. Allow login without password
 7. Let the installation process finish
 
@@ -128,7 +131,7 @@ For example **Jetpack 4.5.1**, which uses **Cuda 10.2** do:
 sudo apt install cuda-libraries-dev-10-1 cuda-nvcc-10-2
 ```
 
-Then, append to the `.bashrc` file located in `/home/icub/`:
+Then, within the `.bashrc`:
 
 ```bash
 export CUDA_HOME=/usr/local/cuda-10.2

docs/icub_operating_systems/other-machines/icub-server-from-scratch.md

@@ -1,5 +1,5 @@
 # The iCub Dedicated Server - Installation from scratch
-Since iCubOS is based on Ubuntu server, we will install Ubuntu server from the default installer and the we manually costimize it.
+Since iCubOS is based on Ubuntu server, we will install Ubuntu server from the default installer and then we manually customize it.
 
 ## Latest versions
 Latest version is based on Ubuntu Server 20.04.2

docs/icub_sw.md

@@ -3,8 +3,10 @@
 - [`Software Installation`](./sw_installation/index.md)
 - [`Software Versioning Table`](./sw_versioning_table/index.md)
 - [`The OS for the iCub environment`](./icub_operating_systems/index.md)
+- [`The OS for the ergoCub environment`](./ergocub_operating_systems/index.md)
 - [`The YARP Documentation`](https://yarp.it/latest/)
 - [`The iCub Software Documentation`](https://robotology.github.io/robotology-documentation/doc/html/index.html)
+- [`The ergoCub Software Documentation`](https://icub-tech-iit.github.io/ergocub-software/)
 - [`How to set up multiple iCubs on the same network`](./icub_setup_multiple_robots/index.md)
 - [`iCub Firmware`](./icub_firmware/index.md)
 - [`iCub Microphones`](./icub_microphones/icub_microphones.md)

docs/index.md

@@ -9,4 +9,4 @@
 
 #### [:gear:{.blink} Documentation resources on the `iCub Hardware`](icub_hw.md)
 
-#### [:computer:{.blink} Documentation resources on the `iCub Software`](icub_sw.md)
+#### [:computer:{.blink} Documentation resources on the `iCub Software`](icub_sw.md)

docs/upgrade_kits/realsense_holder/support.md

@@ -29,7 +29,7 @@ It ensures the compatibility with more RealSense models.
 |     2  | V4-16--_-_ISO7045_CZ|   | screw - M4 x 16 - UNI7687 , DIN7985A , ISO7045 - SS A2 - pozidriv cross recessed pan head |11963|
 
 ## Historical review
-This upgrade kit has been developed together with the [HSP@IIT](https://www.iit.it/web/humanoid-sensing-and-perception) research line as an optional plug-in support to improve iCub perception and facilitate it in grasping tasks iCub. For reference, see also the page [design holder realsense](https://github.com/icub-tech-iit/design-holder-realsense).
+This upgrade kit has been developed together with the [HSP@IIT](https://hsp.iit.it/) research line as an optional plug-in support to improve iCub perception and facilitate it in grasping tasks iCub. For reference, see also the page [design holder realsense](https://github.com/icub-tech-iit/design-holder-realsense).
 
 <center> <img src="../img/1.PNG" height=400> </center>
 

mkdocs.yml

@@ -209,6 +209,13 @@ nav:
           - Manual Installation:
             - icub-head: sw_installation/icub_head_manual.md
       - Software Versioning Table: sw_versioning_table/index.md
+      - The OS for the ergoCub environment:
+        - Summary: ergocub_operating_systems/index.md
+        - Network: ergocub_operating_systems/network.md
+        - ergocub-head:
+          - Jetpack installation: icub_operating_systems/icubos/jetpack.md
+        - ergocub-torso:
+          - Installation from scratch: ergocub_operating_systems/ergocub_torso/install_from_scratch.md
       - The OS for the iCub environment:
         - Summary: icub_operating_systems/index.md
         - The OS on icub-head:

scripts/linkchecker/linkcheckerrc

@@ -1,5 +1,6 @@
 [checking]
 threads=20
+timeout=300
 sslverify=0
 
 [output]