Skip to content

Commit 83087c8

Browse files
authored
Merge pull request #1720 from arduino/taddy/portenta-bash-snippet-update
[PC-1568] Portenta Family Code Format Patch Docs
2 parents 5fadb19 + a249722 commit 83087c8

File tree

25 files changed

+381
-345
lines changed

25 files changed

+381
-345
lines changed

content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ This can be done with **imgtool**. You can download and install it directly from
4747
***`imgtool` is already installed by the mbed platform and can be found in the `%LOCALAPPDATA%\Arduino15\packages\arduino\tools\imgtool` directory on Windows, in `~/.arduino15/packages/arduino/tools/imgtool` on Linux and in `~/Library/Arduino15/packages/arduino/tools/imgtool` on macOS.***
4848

4949
To generate the new keys you can use this command line:
50-
```
50+
51+
```bash
5152
imgtool keygen --key my-sign-keyfile.pem -t ecdsa-p256
5253
imgtool keygen --key my-encrypt-keyfile.pem -t ecdsa-p256
5354
```
@@ -57,7 +58,8 @@ Remember to **save the keys and keep them in a secure location** and not to lose
5758

5859
### 2. Upload the Custom Keys to the Board
5960
Once the keys have been generated, they have to be uploaded to the Portenta H7. This procedure has to be done only once, because it is persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use:
60-
```
61+
62+
```bash
6163
imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-priv-key.h
6264
imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-pub-key.h
6365
```
@@ -71,7 +73,8 @@ To do so, just save the sketch to another location and replace the `ecsda-p256-e
7173
Since the default keys have been changed in favour of custom generated ones, the new ones have to be used when compiling and uploading a sketch, because the compiled sketch is signed and encrypted using such keys.
7274

7375
To override the security keys used during the compile, you have to use the Arduino CLI and specify the keys with:
74-
```
76+
77+
```bash
7578
arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=sien --keys-keychain <path-to-your-keys> --sign-key ecdsa-p256-signing-priv-key.pem --encrypt-key ecdsa-p256-encrypt-pub-key.pem /home/user/Arduino/MySketch
7679
```
7780

content/hardware/04.pro/boards/portenta-x8/tutorials/03.uploading-sketches-m4/content.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ To upload the firmware, you can use the ADB tool that has been installed as part
6666

6767
From that directory, you can use the `adb` tool. To upload your compiled sketch, you will need to use the following command:
6868

69-
```
69+
```bash
7070
adb push <sketchBinaryPath> /tmp/arduino/m4-user-sketch.elf
7171
```
7272

content/hardware/04.pro/boards/portenta-x8/tutorials/04.python-arduino-data-exchange/content.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ temperature = rpc_client.call('temperature')
9999

100100
The complete Python® application files are in the same package as the Arduino sketch (see above). Like in the previous step, upload the `python-sensor-rpc` folder to the X8 via `adb push <local directory path>/python-sensor-rpc /home/fio`. Log into the X8 via `adb shell`. Then navigate into the `python-sensor-rpc` folder and execute `sudo docker build . -t python-sensor-rpc`. When it is finished, you can run the container with `sudo docker-compose up`. After a few seconds, you should see the output from the Python application featuring the sensor readings on the M4 that exchanges through the RPC mechanism. The output should look similar to the following:
101101

102-
```
102+
```bash
103103
python-sensor-rpc_1 | ============================================
104104
python-sensor-rpc_1 | == Portenta X8 Sensor reading ==
105105
python-sensor-rpc_1 | ============================================
@@ -116,7 +116,9 @@ Whenever you change anything in the Python® script on your computer, you will h
116116
```bash
117117
# On your computer
118118
adb push python-sensor-rpc /home/fio
119+
```
119120

121+
```bash
120122
# On X8
121123
sudo docker-compose down
122124
sudo docker build . -t python-sensor-rpc

content/hardware/04.pro/boards/portenta-x8/tutorials/05.docker-container/content.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ In this tutorial, we will go through the steps of how to install, run and remove
4343

4444
The Portenta X8 provides Docker CLI by default. The following command will help you verify if it is installed correctly:
4545

46-
```
46+
```bash
4747
docker -v
4848
```
4949

@@ -63,7 +63,7 @@ First, you will need to search for ["Hello World" container image](https://hub.d
6363

6464
The following command must be used to pull the `hello-world` image. The Docker hub page for images has the instructions to pull the image and deploy the container.
6565

66-
```
66+
```bash
6767
docker pull hello-world
6868
```
6969

@@ -73,7 +73,7 @@ docker pull hello-world
7373

7474
This is the command to begin the container instance.
7575

76-
```
76+
```bash
7777
docker run hello-world
7878
```
7979

@@ -85,15 +85,15 @@ docker run hello-world
8585

8686
The following command will display the active containers and will show the `hello-world` container if it was able to run successfully. The `STATUS` message will let you know if the container is active or has finished operation depending on its purpose.
8787

88-
```
88+
```bash
8989
docker ps -a
9090
```
9191

9292
![Docker CLI listing all the active containers](assets/docker-ps.png)
9393

9494
The list of available images, including installed `hello-world` image, can be verified using the following command:
9595

96-
```
96+
```bash
9797
docker images
9898
```
9999

@@ -103,15 +103,15 @@ docker images
103103

104104
You will need to obtain an assigned `CONTAINER ID` to be able to remove a container of your choice. The list of active containers provides this information. The remove (`rm`) command is then used with the desired container identifier to proceed with the removal process.
105105

106-
```
106+
```bash
107107
docker container rm <CONTAINER ID>
108108
```
109109

110110
For this example, the command `docker ps -a` will show the `CONTAINER ID` of the `hello-world` container designated as: `c44ba77b65cb`. If you encounter an error stating that the container cannot be removed, it may mean that the container has an actively ongoing operation which can be checked with `STATUS` message.
111111

112112
Granted that this is the case, you will need to stop the container and verify with `STATUS` message that it has exited successfully. To do this, the following command is used:
113113

114-
```
114+
```bash
115115
docker stop <CONTAINER ID>
116116
```
117117

@@ -123,7 +123,7 @@ Using the `docker ps -a` after container removal, the `hello-world` container sh
123123

124124
The same goes for the images if you would like to free some space. The removal command will now be as follows using `IMAGE ID` found within the image table:
125125

126-
```
126+
```bash
127127
docker rmi <IMAGE ID>
128128
```
129129

content/hardware/04.pro/boards/portenta-x8/tutorials/06.waves-fleet-managment/content.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -46,19 +46,19 @@ For security purposes, we recommend that you rotate your FoundriesFactory keys.
4646

4747
First, we will rotate the root keys. These are the most important keys, as they are used to create new target keys. Rotate them with the command:
4848

49-
```
49+
```bash
5050
fioctl keys rotate-root --initial /absolute/path/to/root.keys.tgz
5151
```
5252

5353
Now we can rotate the target-only keys with following command:
5454

55-
```
55+
```bash
5656
fioctl keys rotate-targets /absolute/path/to/root.keys.tgz
5757
```
5858

5959
And finally, for security reasons, we separating the target keys from the root using the following command:
6060

61-
```
61+
```bash
6262
fioctl keys copy-targets /absolute/path/to/root.keys.tgz /path/to/target.only.key.tgz
6363
```
6464

@@ -68,13 +68,13 @@ Now we can move on to creating our Wave.
6868

6969
Before a Factory can start making production OTAs, an initial production Targets file must be created. For more information, please check out [here](https://docs.foundries.io/latest/reference-manual/ota/production-targets.html). We can begin by creating a dummy wave with the command:
7070

71-
```
71+
```bash
7272
fioctl wave init -k /absolute/path/to/targets.only.key.tgz populate-targets
7373
```
7474

7575
Then complete the Wave with:
7676

77-
```
77+
```bash
7878
fioctl wave complete populate-targets
7979
```
8080

@@ -84,19 +84,19 @@ This creates a new `targets.json` file for production devices, subscribing to th
8484

8585
Now we can start creating our Wave. The command below will create a Wave that is pushable to our devices. To create a Wave, we will sign it with a key, and here we will use the targets-only key. Then we give the Wave a name, target number, and tag. The `target number` needs to correspond to the target that we want the Wave to contain for our devices. The `tag` can be set as production or development.
8686

87-
```
87+
```bash
8888
fioctl wave init -k /absolute/path/to/targets.only.key.tgz <waveName> <targetNumber> <tag>
8989
```
9090

9191
And then we can complete the Wave by passing the name to the "complete" function:
9292

93-
```
93+
```bash
9494
fioctl wave complete <waveName>
9595
```
9696

9797
If you decide to cancel, the following command will help you to do that:
9898

99-
```
99+
```bash
100100
fioctl waves cancel <waveName>
101101
```
102102

@@ -108,13 +108,13 @@ After creating the Wave, you should see it on your Factory page. It should also
108108

109109
With this command, we create our group, giving it a name and a short description:
110110

111-
```
111+
```bash
112112
fioctl config device-group create <groupName> "<shortDescription>"
113113
```
114114

115115
The name and the short description should be as explicit and concise as possible to highlight its group. Now to assign a device to our group we use the following command:
116116

117-
```
117+
```bash
118118
fioctl device config group <deviceName> <groupName>
119119
```
120120

@@ -124,7 +124,7 @@ On your FoundriesFactory device page, you can sort and view devices by the group
124124

125125
To roll out our Wave to our device group, use the following command:
126126

127-
```
127+
```bash
128128
fioctl waves rollout <waveName> <deviceGroupName>
129129
```
130130

content/hardware/04.pro/boards/portenta-x8/tutorials/07.custom-container/content.md

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ To pull or push repositories, you have to generate an API key. This is done by g
147147

148148
Use the following command in git on your machine. To get the repository on your machine, replace "YOUR_FACTORY" with the name of your Factory. The "-b" parameter specifies a branch to checkout after cloning the repository. Running this command will get the container repository, where we will put our folder.
149149

150-
```
150+
```bash
151151
git clone https://source.foundries.io/factories/YOUR_FACTORY/containers.git -b devel
152152
```
153153

@@ -157,48 +157,51 @@ Put the "x8-custom-test" folder in the repository and push it with git. When you
157157

158158
After the build finishes, it can take up to 10 minutes for your device to update over-the-air to this new version. You can inspect it via the "Devices" tab of your FoundriesFactory. After your device takes the update, navigate into the "x8-custom-test" folder, which should be located on your board now. This allows us to build our container with a simple command. Using ```docker build``` with a ```--tag``` will let us give the container a tag so we can easily keep track of what version of the build this is.
159159

160-
```python
160+
```bash
161161
docker build --tag "x8-custom-test:latest" .
162162
```
163163

164164
Now that it is built, we can run it with ```docker run```, finding it with the tag that we chose to give to the build we want to run. Here we need to enter the user information into the --user tag. This information is found inside the "docker-compose.yml" file.
165165

166-
```python
166+
```bash
167167
docker run -it --rm --user "63" x8-custom-test:latest
168168
```
169169

170170
### Using Docker-Compose
171171

172172
An option for testing an app or container is to use "docker-compose". It is helpful when we have a lot of settings in our "docker-compose.yml" file since we don't have to use those settings in the run argument with this method. First, navigate into the container folder.
173173

174-
```python
174+
```bash
175175
cd /home/fio/x8-custom-test
176176
```
177177

178178
This docker-compose command will start your application and register it as a systemd service that will persist even when a reboot occurs. So at the next boot, your docker-compose app will run automatically.
179179

180-
```python
180+
```bash
181181
docker-compose up --detach
182182
```
183183

184184
To stop the docker-compose app from running, use the following command:
185185

186-
```python
186+
```bash
187187
docker-compose stop
188188
```
189189

190190
## Deploying with Docker Hub
191191

192192
An alternative method to deploy the custom container is by using the Docker Hub platform. For this, it needs a [Docker Hub account](https://hub.docker.com/) to have your own repository to have the custom container uploaded. When you have the repository ready, the following command will let you upload the custom container image.
193193

194-
```
194+
```bash
195195
docker push HUB_USERNAME/x8-custom-test
196196
```
197197

198198
The custom container image can now be found within `HUB_USERNAME` Docker Hub repository. The image can be accessed whenever any connectivity type grants access to the container image. To pull the image and deploy the container, you will need to connect the Portenta X8 via ADB and use following commands in sequence:
199199

200-
```
200+
```bash
201201
adb shell
202+
```
203+
204+
```bash
202205
docker pull x8-custom-test
203206
```
204207

content/hardware/04.pro/boards/portenta-x8/tutorials/08.image-building/content.md

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,16 +44,19 @@ You will create a Docker image that has the dependencies needed to build your de
4444

4545
First, clone the lmp-manifest repository with the following command:
4646

47-
```
47+
```bash
4848
git clone https://github.com/arduino/lmp-manifest.git
4949
```
5050

5151
![Cloning lmp-manifest repository](assets/git_clone_lmp-manifest.png)
5252

5353
After cloning the lmp-manifest repository successfully, we will proceed to build the Docker Image using following command sequence:
5454

55-
```
55+
```bash
5656
cd lmp-manifest
57+
```
58+
59+
```bash
5760
docker build -t yocto-build ./lmp-manifest
5861
```
5962

@@ -69,13 +72,13 @@ Once the *Docker Image* is ready, we will run the image with the `-v` argument t
6972

7073
Run the `yocto-build` builder image with following command:
7174

72-
```
75+
```bash
7376
docker run -v <source>:/dockerVolume -it yocto-build bash
7477
```
7578

7679
We need to switch to the `builder` user with the following command after the previous process, and the password is **builder**:
7780

78-
```
81+
```bash
7982
su builder
8083
```
8184

@@ -89,7 +92,7 @@ Now that you are running inside the Docker Image, you can use tools like **git-r
8992

9093
First, configure git with your credentials. They don't need to be the real ones but are required by `git-repo` to pull. The following commands can be used for this example:
9194

92-
```
95+
```bash
9396
git config --global user.email "you@example.com"
9497
git config --global user.name "Your Name"
9598
```
@@ -98,7 +101,7 @@ git config --global user.name "Your Name"
98101

99102
Change to the home directory, and initialize the repository using **repo**:
100103

101-
```
104+
```bash
102105
cd /dockerVolume
103106
repo init -u https://github.com/arduino/lmp-manifest.git -m arduino.xml -b release
104107
```
@@ -107,7 +110,7 @@ repo init -u https://github.com/arduino/lmp-manifest.git -m arduino.xml -b relea
107110

108111
Then pull the needed files with:
109112

110-
```
113+
```bash
111114
repo sync
112115
```
113116

@@ -149,7 +152,7 @@ You will be able to see similar output as following after the previous steps:
149152

150153
To start building the image, following command is used:
151154

152-
```
155+
```bash
153156
bitbake lmp-partner-arduino-image
154157
```
155158

@@ -174,7 +177,7 @@ If possible, it is a good practice to understand the available threads of your c
174177

175178
To flash your board, you will need to compile **lmp-mfgtool distro** to get additional tools. First, go into your home folder and change `DISTRO` following the command sequence:
176179

177-
```
180+
```bash
178181
cd ..
179182
DISTRO=lmp-mfgtool MACHINE=portenta-x8 . setup-environment
180183
echo "ACCEPT_FSL_EULA = \"1\"" >> conf/local.conf
@@ -189,7 +192,7 @@ You should be able to see similar results as following image when successful:
189192

190193
To compile and get the tools required, we will use following command:
191194

192-
```
195+
```bash
193196
bitbake mfgtool-files
194197
```
195198

@@ -205,7 +208,7 @@ After completion:
205208

206209
After a successful build, save the needed files to the host volume you mounted with `docker run`. Use the following commands to copy the files to your storage unit:
207210

208-
```
211+
```bash
209212
cd ..
210213
mkdir ../../dockerVolume/flashing
211214
DEPLOY_FOLDER=../../dockerVolume/flashing

0 commit comments

Comments
 (0)