Skip to content

Commit

Permalink
Merge branch 'icub-tech-iit:master' into master
Browse files Browse the repository at this point in the history
  • Loading branch information
@simeonedussoni
simeonedussoni authored Oct 20, 2023
2 parents e96d553 + 0f2fdaa commit ff0a7cb
Show file tree
Hide file tree
Showing 60 changed files with 862 additions and 400 deletions.
8 changes: 5 additions & 3 deletions .github/workflows/check-links.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,17 @@ jobs:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@main
- name: Dependencies
run: |
pip3 install git+https://github.com/linkchecker/linkchecker.git
pip install --user git+https://github.com/linkchecker/linkchecker.git
echo "${HOME}/.local/bin" >> ${GITHUB_PATH}
- name: Fetch repository name
id: repo-name
run: |
echo "REPOSITORY_NAME=$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')" >> $GITHUB_OUTPUT
echo "REPOSITORY_NAME=$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')" >> ${GITHUB_OUTPUT}
- name: Run checker
run: |
linkchecker https://${{ github.repository_owner }}.github.io/${{ steps.repo-name.outputs.REPOSITORY_NAME }}
linkchecker --config=./scripts/linkchecker/linkcheckerrc https://${{ github.repository_owner }}.github.io/${{ steps.repo-name.outputs.REPOSITORY_NAME }}/
3 changes: 3 additions & 0 deletions .gitpod.Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
FROM ubuntu:latest
LABEL org.opencontainers.image.authors="Ugo Pattacini <[email protected]>"

# Increment this variable to force Docker to build the image for the sections below w/o relying on cache
ENV INVALIDATE_DOCKER_CACHE_ALL=0

ENV DEBIAN_FRONTEND=noninteractive

RUN apt update && \
Expand Down
Binary file added docs/battery_boards/bat_board/assets/bat-2-ems-R1-connection-01.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/battery_boards/bat_board/assets/bat-2-ems-R1-connection-02.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
104 changes: 104 additions & 0 deletions docs/battery_boards/bat_board/bat_protocol.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# BAT board Protocol

## Introduction
This page describes the `BAT` board and its protocol. Basically, this board is responsible for the management of the data and signals provided by the battery pack in `R1`, `iCub`, and `ergoCub` robots. Moreover, it should be noted that in these robots it is always coupled with the `BMS` board, which is responsible for fine-tuning and managing the battery pack status.
In general, as shown in the figures below (illustrating the connection between the BAT and EMS boards in the base of `R1/SN003`), the `BAT` can be connected to an EMS board through the `CAN` connector devoted to receiving the CAN frames sent out by the `BAT`.

<center>
<table><tr>
<td><img width="500" height="500" src="../assets/bat-2-ems-R1-connection-01.png"/></td>
<td><img width="500" height="500" src="../assets/bat-2-ems-R1-connection-02.png"/></td>
</tr></table>
</center>

Specifically, at the current status of the development (July 2023), the `BAT` board can send the following data:

- Battery Pack Voltage in Volt.
- Battery Pack Charge in $\%$.
- Battery Pack Status (detail will follow).

### Communication characteristics
The `BAT` board sends the pieces of information detailed above with a FIFO cycle of 1 ms. Then, the `EMS` board handles the CAN frames sent by the `BAT`, parses them, and finally forwards them to the higher level of the `yarprobotinterface` at the specific port defined in the configuration files with a frequency of 1 Hz.
Furthermore, that info is also sent directly from the `BAT` to the display attached to the robot, every 10 ms.

### Types of data transmitted

As mentioned at the end of the [introduction section](#introduction), the CAN frames sent by the `BAT` to the `EMS` and parsed by this latter board are:

- Battery pack info message sent at address `0x620` as:

| Byte | Value | Description |
|:---:|:---:|:---|
| 0 | Vbattery & 0xFF | LSBs of the battery pack voltage |
| 1 | (Vbattery >> 8) & 0xFF | MSBs of the battery pack voltage |
| 2 | 0x00 | Not used |
| 3 | 0x00 | Not used |
| 4 | battery_charge & 0xFF | byte of the battery pack charge |
| 5 | 0x00 | Not used |
| 6 | 0x00 | Not used |
| 7 | 0x00 | Not used |

- Battery pack status message sent at address `0x629` as:

| Byte | Value | Description |
|:---:|:---:|:---|
| 0 | DCDC_status_A & 0xFF | DCDC status A |
| 1 | DCDC_status_B & 0xFF | DCDC status A |
| 2 | 0x00 | Not used |
| 3 | 0x00 | Not used |
| 4 | 0x00 | Not used |
| 5 | 0x00 | Not used |
| 6 | 0x00 | Not used |
| 7 | 0x00 | Not used |

where:

- DCDC_status_A (bits are summed up together):

Position | BIT[7] | BIT[6] | BIT[5] | BIT[4] | BIT[3] | BIT[2] | BIT[1] | BIT[0] |
|:---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
Value | V12board | V12board_F | V12motor | V12motor_F | HSM | HSM_PG | HSM_F | HSM_broken |
Description | 12V DCDC board regulator | 12V DCDC board regulator OVERCURRENT fault | 12V DCDC motor regulator | 12V DCDC motor regulator OVERCURRENT fault | Hot Swap Manager | Hot Swap Manager POWER GOOD | Hot Swap Manager OVERCURRENT/OVERVOLTAGE fault | Hot Swap Manager MOSFETs damaged |
Possible status | ON(1)/OFF(0) | OC/NORMAL | ON/OFF | OC/NORMAL| ON/OFF | HSM output voltage stable after transient/HSM output voltage not guaranteed | OC-OV/NORMAL | HSM MOSFETs probably burned/NORMAL |

- DCDC_status_B:

Position | BIT[3] | BIT[2] | BIT[1] | BIT[0] |
|:---|:---:|:---:|:---:|:---:|
Value | HSM_SW_F | HSM_HW_F | PB1_restart | PB2_restart |
Description | OC Fault on the HSM triggered by overcurrent (threshold defined in the FW) | OC Fault on the HSM triggered by FLT Pin on the HSM micro | Restart phase of the push button 1 | Restart phase of the push button 2 |
Possible status | FAULT_OFF(0)/FAULT_ON(1) | FAULT_OFF(0)/FAULT_ON(1) | Start-up phase(1)/stable operation(0) | Start-up phase/stable operation |

- Final status shown at the port is equal to:

`(DCDC_status_B << 8 ) | DCDC_status_A`

Thereby, the end user sees a decimal number on the BAT Display, which can be transformed into BITs and analyzed as described below:

| BIT Position | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| VALUE | NAN | NAN | NAN | NAN | HSM_SW_F | HSM_HW_F | PB1 | PB2 | V12board | V12board_F | V12motor | V12motor_F | HSM | HSM_PG | HSM_F | HSM_broken |

```console
Example:

If we get 172 as a decimal value, then we will have in bits:

0000 0000 1010 1100

The active bits are thus related to:
- HSM_PG
- HSM
- V12motor
- V12board
```

### Data displayed on the YARP port
The user gets the data from a specific YARP port defined in the configuration file. Here's the format:

- Voltage is displayed in the Volts.
- Battery charge is displayed in $\%$.
- Status is displayed as a 16-bit integer (only the first 10 bits are valid), whose mapping adheres to the tables above.

Moreover, at start-up, a **DEBUG** message with the initial values of the status (converted to the description strings) is sent to `yarprobotinterface`.
Then, each time the status changes, a **DEBUG** message is sent to `yarprobotinterface`, which in turn prints out a description only about the values of those bits that have switched.
0 docs/bcb_board/assets/fig-1.png → ...battery_boards/bcb_board/assets/fig-1.png
View file
File renamed without changes
0 docs/bcb_board/assets/fig-2.png → ...battery_boards/bcb_board/assets/fig-2.png
View file
File renamed without changes
0 docs/bcb_board/bcb_bluetooth_protocol.md → ...oards/bcb_board/bcb_bluetooth_protocol.md
View file
File renamed without changes.
5 changes: 5 additions & 0 deletions docs/battery_boards/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Battery Documentation
Here you can find information about different boards related to the battery in the various versions of the robot and some related resources.

- [**BCB Board Documentation**](./bcb_board/bcb_bluetooth_protocol.md)
- [**BAT Board Documentation**](./bat_board/bat_protocol.md)
8 changes: 2 additions & 6 deletions docs/ergoCub1_wiring/ergoCub1_0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,5 @@ The system architecture of ergoCub1.0 is depicted in the following image:

### Logic and Harness ergoCub 1.0 E1.0 Full Robot

- [ergoCub1.0 Logic_1.2.0](https://github.com/icub-tech-iit/electronics-wiring-public/blob/master/ergocub1/ergocub1.0/pdf/ergoCub1.1_E1.0_16963_1.2.0_Logic.pdf)
- [ergoCub1.0 Harness_1.2.0](https://github.com/icub-tech-iit/electronics-wiring-public/blob/master/ergocub1/ergocub1.0/pdf/ergoCub1.1_E1.0_16965_1.2.0_Harness.pdf)

!!! note "note"
motor and board placement is still under development

- [ergoCub1.0 Logic_1.0.0](https://github.com/icub-tech-iit/electronics-wiring-public/blob/master/ergocub1/ergocub1.0/pdf/ergoCub1.0_E1.0_16963_1.0.0_Logic.pdf)
- [ergoCub1.0 Harness_1.0.0](https://github.com/icub-tech-iit/electronics-wiring-public/blob/master/ergocub1/ergocub1.0/pdf/ergoCub1.0_E1.0_16965_1.0.0_Harness.pdf)
4 changes: 2 additions & 2 deletions docs/hands/hands_mk5.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@
| Joint number | Motors | Identifier | Type | Parent link | Child link | HW lower limit | HW upper limit | SW low. l. | SW upp. l. | Notes |
|--------------|--------|---------------|------|-----------------|-----------------|----------------|----------------|------------|------------|------------|
| | | l_thumb_add | ROT | l_hand_palm | l_hand_thumb_1 | 0° | 90° | | | T1 in fig. |
| | | l_thumb_prox | ROT | l_hand_thumb_1 | l_hand_thumb_2 | 0° | 90° | | | T2 in fig. |
| | | l_thumb_dist | ROT | l_hand_thumb_2 | l_hand_thumb_3 | 0° | 59.2° | | | T3 in fig. |
| | | l_thumb_prox | ROT | l_hand_thumb_1 | l_hand_thumb_2 | 0° | 82.1° | | | T2 in fig. |
| | | l_thumb_dist | ROT | l_hand_thumb_2 | l_hand_thumb_3 | 0° | 53.6° | | | T3 in fig. |
| | | l_index_add | ROT | l_hand_palm | l_hand_index_1 | 0° | 15° | | | I1 in fig. |
| | | l_index_prox | ROT | l_hand_index_1 | l_hand_index_2 | 0° | 90° | | | I2 in fig. |
| | | l_index_dist | ROT | l_hand_index_2 | l_hand_index_3 | 0° | 99.2° | | | I3 in fig. |
Expand Down
54 changes: 27 additions & 27 deletions docs/hands/hands_mk5_coupling.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,33 +69,33 @@ $$q_{1} = \tan^{- 1}\left( \frac{A_{y}(q_{0}) - P_{0y}}{A_{x}(q_{0}) - P_{0x}} \

The following table describes the coupling variables of the finger mechanisms in the **hand Mk5.1**.

| Name | UoM | | | Values | | | Description | | | |
|-------------|-----|-----------|-----------|------------|----------|-----------|------------------------------------------------------------------------------------|---|---|---|
| | | **THUMB** | **INDEX** | **MIDDLE** | **RING** | **PINKY** | | | | |
| $L_{0x}$ | mm | -5 | -5 | -5 | -5 | -5 | $x$ coordinate of the first end of the leverism | | | |
| $L_{0y}$ | mm | 4 | 4 | 4 | 4 | 4 | $y$ coordinate of the the first end of the leverism | | | |
| $L_{1x}$ | mm | 29 | 34 | 34 | 34 | 29 | $x$ coordinate of the second end of the leverism | | | |
| $L_{1y}$ | mm | 0.8 | 0.8 | 0.8 | 0.8 | 0.5 | $y$ coordinate of the second end of the leverism | | | |
| $P_{1x}$ | mm | 35 | 40 | 40 | 40 | 35 | $x$ coordinate of the axis of the joint between the first and the second phalanx | | | |
| $P_{1y}$ | mm | 1.5 | 1.5 | 1.5 | 1.5 | 1.5 | $y$ coordinate of the axis of the joint between the first and the second phalanx | | | |
| | | | | | | | | | | |
| $q_{0off}$ | deg | -97.54 | -97.54 | -97.54 | -97.54 | -97.52 | Angle of $A-C$ when the finger is fully open | | | |
| $q_{2bias}$ | deg | -173.35 | -173.35 | -173.35 | -173.35 | -170.53 | Angle of $L_1-P_1$ when the finger is fully open | | | |
| $q_{1off}$ | deg | 2.45 | 2.15 | 2.15 | 2.15 | 2.46 | Angle of $P_1-P_0$ when the finger is fully open | | | |
| $q_{1bias}$ | deg | -90 | -90 | -90 | -90 | -90 | Angle of $B-P_0$ when the finger is fully open | | | |
| | | | | | | | | | | |
| $q_{0max}$ | deg | -12 | -12 | -12 | -12 | -11.97 | Max value of $q_0$, i.e. when the finger is fully closed | | | |
| $q_{1max}$ | deg | 90 | 90 | 90 | 90 | 90 | Max value of $q_1$, same as above | | | |
| $q_{2max}$ | deg | 191.44 | 193.06 | 193.06 | 193.06 | 188.7 | Max value of $q_2$, same as above | | | |
| | | | | | | | | | | |
| $k$ | mm | 17.1 | 29.18 | 29.18 | 29.18 | 24.25 | Connecting rod length, $\|L_1-L_0\|$ | | | |
| $d$ | mm | 20.06 | 30.04 | 30.04 | 30.04 | 25.04 | Distance between the two joints, $P_1$ and $P_0$ | | | |
| $l$ | mm | 8.5 | 6.04 | 6.04 | 6.04 | 6.08 | Distance between $L_1$ and $P_1$ | | | |
| $b$ | mm | 6.24 | 6.4 | 6.4 | 6.4 | 6.4 | Distance between $L_0$ and $P_0$ | | | |
| $s$ | mm | 6.52 | 5.5 | 5.5 | 5.5 | 5.5 | Distance between joint $B$ of the connecting rod $A-B$ and joint $P_0$ | | | |
| $t$ | mm | 13 | 14.5 | 14.5 | 14.5 | 14.5 | Length of the connecting rod $A-B$ | | | |
| $f$ | mm | 6 | 5.5 | 5.5 | 5.5 | 5.5 | Length of the connecting rod $A-C$ | | | |
| $r$ | mm | 7.5 | 8.5 | 8.5 | 8.5 | 8.5 | Length of the connecting rod $D-C$ | | | |
| Name | UoM | | | Values | | | Description |
|-------------|-----|-----------|-----------|------------|----------|-----------|------------------------------------------------------------------------------------|
| | | **THUMB** | **INDEX** | **MIDDLE** | **RING** | **PINKY** | |
| $L_{0x}$ | mm | -5 | -5 | -5 | -5 | -5 | $x$ coordinate of the first end of the leverism |
| $L_{0y}$ | mm | 4 | 4 | 4 | 4 | 4 | $y$ coordinate of the the first end of the leverism |
| $L_{1x}$ | mm | 29 | 34 | 34 | 34 | 29 | $x$ coordinate of the second end of the leverism |
| $L_{1y}$ | mm | 0.8 | 0.8 | 0.8 | 0.8 | 0.5 | $y$ coordinate of the second end of the leverism |
| $P_{1x}$ | mm | 35 | 40 | 40 | 40 | 35 | $x$ coordinate of the axis of the joint between the first and the second phalanx |
| $P_{1y}$ | mm | 1.5 | 1.5 | 1.5 | 1.5 | 1.5 | $y$ coordinate of the axis of the joint between the first and the second phalanx |
| | | | | | | | |
| $q_{0off}$ | deg | -97.54 | -97.54 | -97.54 | -97.54 | -97.52 | Angle of $A-C$ when the finger is fully open |
| $q_{2bias}$ | deg | -173.35 | -173.35 | -173.35 | -173.35 | -170.53 | Angle of $L_1-P_1$ when the finger is fully open |
| $q_{1off}$ | deg | 2.45 | 2.15 | 2.15 | 2.15 | 2.46 | Angle of $P_1-P_0$ when the finger is fully open |
| $q_{1bias}$ | deg | -90 | -90 | -90 | -90 | -90 | Angle of $B-P_0$ when the finger is fully open |
| | | | | | | | |
| $q_{0max}$ | deg | -12 | -12 | -12 | -12 | -11.97 | Max value of $q_0$, i.e. when the finger is fully closed |
| $q_{1max}$ | deg | 90 | 90 | 90 | 90 | 90 | Max value of $q_1$, same as above |
| $q_{2max}$ | deg | 191.44 | 193.06 | 193.06 | 193.06 | 188.7 | Max value of $q_2$, same as above |
| | | | | | | | |
| $k$ | mm | 34.15 | 39.13 | 39.13 | 39.13 | 34.18 | Connecting rod length, $\|L_1-L_0\|$ |
| $d$ | mm | 35.03 | 40.03 | 40.03 | 40.03 | 35.03 | Distance between the two joints, $P_1$ and $P_0$ |
| $l$ | mm | 6.04 | 6.04 | 6.04 | 6.04 | 6.08 | Distance between $L_1$ and $P_1$ |
| $b$ | mm | 6.4 | 6.4 | 6.4 | 6.4 | 6.4 | Distance between $L_0$ and $P_0$ |
| $s$ | mm | 5.5 | 5.5 | 5.5 | 5.5 | 5.5 | Distance between joint $B$ of the connecting rod $A-B$ and joint $P_0$ |
| $t$ | mm | 14.5 | 14.5 | 14.5 | 14.5 | 14.5 | Length of the connecting rod $A-B$ |
| $f$ | mm | 5.5 | 5.5 | 5.5 | 5.5 | 5.5 | Length of the connecting rod $A-C$ |
| $r$ | mm | 8.5 | 8.5 | 8.5 | 8.5 | 8.5 | Length of the connecting rod $D-C$ |



Expand Down
Loading

0 comments on commit ff0a7cb

Please sign in to comment.