/
02_2_software.md
143 lines (92 loc) · 6.13 KB
/
02_2_software.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# Software
Follow the steps below for a default installation of the ESP32-C3 platform tooling.
🔎 Should you desire a customized installation (e.g. building parts from source, or add support for Xtensa/ESP32-S3), instructions for doing so can be found in the [Installing Rust](https://esp-rs.github.io/book/dependencies/installing-rust.html) chapter of the *Rust on ESP* Book.
## Rust toolchain
✅ If you haven't got Rust on your computer, obtain it via <https://rustup.rs/>
Furthermore, for ESP32-C3, a specific *nightly* version of the Rust toolchain is currently required.
✅ Install nightly Rust and add support for the target architecture using the following console commands:
```console
$ rustup install nightly-2022-03-10
$ rustup component add rust-src --toolchain nightly-2022-03-10
```
🔎 Rust is capable of cross-compiling to any supported target (see `rustup target list`). By default, only the native architecture of your system is installed.
To build for the Xtensa architecture (*not* part of this material), a fork of the Rust compiler is required as of January 2022.
## Espressif toolchain
Several tools are required:
- `cargo-espflash` - upload firmware to the microcontroller
- `ldproxy` - Espressif build toolchain dependency
✅ Install them with the following command:
```console
$ cargo install cargo-espflash ldproxy
```
## Toolchain dependencies
### Debian/Ubuntu
```console
$ sudo apt install llvm-dev libclang-dev clang
```
### macOS
(when using the Homebrew package manager, which we recommend)
```console
$ brew install llvm
```
### Troubleshooting
- Python 3 is a required dependency. It comes preinstalled on stock macOS and typically on desktop Linux distributions. An existing **Python 2** installation with the `virtualenv` add-on pointing to it is known to potentially cause build problems.
- Error `failed to run custom build command for libudev-sys v0.1.4` or `esp-idf-sys v0.30.X`:
At time of writing, this can be solved by
1. running [this line](https://github.com/esp-rs/rust-build/blob/f773036483333f3b4618d988f9a1eda051573cb2/support/esp-rs-rust/Containerfile#L13) from the `esp-rs` container:
`apt-get update \
&& apt-get install -y vim nano git curl gcc ninja-build cmake libudev-dev python3 python3-pip libusb-1.0-0 libssl-dev \
pkg-config libtinfo5`
2. restarting the terminal
3. If this is not working, try `cargo clean`, remove the `~/.espressif` folder and reinstall [according to esp instructions](
https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html).
⚠️ In [step 2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-2-get-esp-idf), do not clone the `https://github.com/espressif/esp-idf.git` repository. For this training, we are using a git tag.
Instead, do the following:
```console
git clone --recursive --depth 1 --shallow-submodules git@github.com:espressif/esp-idf.git --branch "v4.4.1" esp-idf-v4.4
cd esp-idf-v4.4
./install.sh esp32c3
. ./export.sh
```
If you change terminal, you will need to source the `export.sh` file:
```console
source ~/esp/esp-idf-v4.4/export.sh
```
4. On Ubuntu, you might need to change your kernel to `5.19`. Run `uname -r` to obtain your kernel version.
## Docker
> ❗️ Please **note** the Docker container provides an alternative option to **compile** the Rust exercises in.
> It is meant for users that have experience with virtualized environments.
> Be aware that we cannot provide help for Docker specific issues during the training.
An alternative environment to **compile** the Rust exercises in is to use Docker. In this repository there is a `Dockerfile`
with instructions to install the Rust toolchain & all required packages. This virtualized environment is designed
to only compile the binaries for the espressif target. Other commands, e.g. using `cargo-espflash`, still need to
be executed on the host system.
✅ Install [`Docker`](https://docs.docker.com/get-docker/) for your operating system.
To build the Docker image run the following command from the root folder:
```console
$ docker image build --tag esp --file .devcontainer/Dockerfile .
```
Building the image takes a while depending on the OS & hardware (20-30 minutes).
To start the new Docker container run:
```console
$ docker run --mount type=bind,source="$(pwd)",target=/workspace,consistency=cached -it esp /bin/bash
```
This starts an interactive shell in the Docker container. It also mounts the local repository to a folder
named `/workspace` inside the container. Changes to the project on the host system are reflected inside the container & vice versa.
Using this Docker setup requires certain commands to run inside the container, while other have to be executed on the host system.
It's recommended to keep two terminals open, one connected to the Docker container, one on the host system.
* in the container: compile the project
* on the host: use the `cargo-espflash` sub-command to flash the program onto the embedded hardware
## Additional Software
### VS Code
One editor with good Rust support is [VS Code](https://code.visualstudio.com/) which is available for most platforms.
When using VS Code we recommend the following extensions to help during the development.
* `Even Better TOML` for editing TOML based configuration files
* [`Rust Analyzer`](https://rust-analyzer.github.io/) to provide code completion & navigation
There are a few more useful extensions for advanced usage
* [`lldb`](https://github.com/vadimcn/vscode-lldb) a native debugger extension based on LLDB
* [`crates`](https://github.com/serayuzgur/crates) to help manage Rust dependencies
### VS Code & Devcontainer
One extension for VS Code that might be helpful to develop inside a Docker container is [`Remote Containers`](https://github.com/Microsoft/vscode-remote-release).
It uses the same `Dockerfile` as the Docker setup, but builds the image and connects to it from within VS Code.
Once the extension is installed VS Code recognizes the configuration in the `.devcontainer` folder. Use the `Remote Containers - Reopen in Container` command to connect VS Code to the container.