Skip to content

Commit 40cfc0c

Browse files
ThomasFarstrikeThomasFarstrike
committed
update docs
1 parent 315a1c5 commit 40cfc0c

File tree

6 files changed

+138
-135
lines changed

6 files changed

+138
-135
lines changed

‎build.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
pip3 install mkdocs mkdocs-material
1+
pip3 install mkdocs mkdocs-material markdown-include
22
mkdocs build

‎docs/os-development/building-for-esp32.md‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎docs/os-development/compile-and-run.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
## Compile the code
2+
3+
1. **Make sure you're in the main repository**:
4+
5+
```
6+
cd MicroPythonOS
7+
```
8+
9+
2. **Start the Compilation**
10+
11+
Usage:
12+
13+
<pre>
14+
```
15+
./scripts/build_lvgl_micropython.sh <target system> <build type (prod or dev)> [optional target device]
16+
```
17+
</pre>
18+
19+
**Target systems**: esp32, unix (= Linux) and macOS
20+
21+
**Build types**:
22+
23+
- A "prod" build includes the complete filesystem that's "frozen" into the build, so it's fast and all ready to go but the files in /lib and /builtin will be read-only.
24+
- A "dev" build comes without a filesystem, so it's perfect for power users that want to work on MicroPythonOS internals. There's a simple script that will copy all the necessary files over later, and these will be writeable.
25+
26+
_Note_: for unix and macOS systems, only "dev" has been tested. The "prod" builds might have issues but should be made to work soon.
27+
28+
**Target devices**: waveshare-esp32-s3-touch-lcd-2 or fri3d-2024
29+
30+
**Examples**:
31+
32+
<pre>
33+
```
34+
./scripts/build_lvgl_micropython.sh esp32 prod fri3d-2024
35+
./scripts/build_lvgl_micropython.sh esp32 dev waveshare-esp32-s3-touch-lcd-2
36+
./scripts/build_lvgl_micropython.sh esp32 unix dev
37+
./scripts/build_lvgl_micropython.sh esp32 macOS dev
38+
```
39+
</pre>
40+
41+
The resulting build file will be in `lvgl_micropython/build/`, for example:
42+
43+
- lvgl_micropython/build/lvgl_micropy_unix
44+
- lvgl_micropython/build/lvgl_micropy_macOS
45+
- lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-16.bin
46+
47+
## Running on Desktop
48+
49+
1. Download a release binary (e.g., `MicroPythonOS_amd64_Linux`, `MicroPythonOS_amd64_MacOS`) or build your own [on MacOS](macos.md) or [Linux](linux.md).
50+
2. Run the application:
51+
52+
<pre>
53+
```
54+
cd internal_filesystem/ # make sure you're in the right place to find the filesystem
55+
/path/to/release_binary -X heapsize=32M -v -i -c "$(cat boot_unix.py main.py)"
56+
```
57+
</pre>
58+
59+
There's also a convenient `./scripts/run_desktop.sh` script that will attempt to start the latest build that you compiled yourself.
60+
61+
### Modifying files
62+
63+
You'll notice that, whenever you change a file on your local system, the changes are immediately visible whenever you reload the file.
64+
65+
This results in a very quick coding cycle.
66+
67+
Give this a try by editing `internal_filesystem/builtin/apps/com.micropythonos.about/assets/about.py` and then restarting the "About" app. Powerful stuff!

‎docs/os-development/installing-on-esp32.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
The easiest way to install on the ESP32 is using the [webinstaller](https://install.MicroPythonOS.com), of course.
2+
3+
But if you need to install a version that's not available there, or you built your own, then you can manually install it on an ESP32 device.
4+
5+
1. **Get the firmware**
6+
7+
- Download a release binary (e.g., `MicroPythonOS_fri3d-2024_prod_0.2.1.bin`, `MicroPythonOS_waveshare-esp32-s3-touch-lcd-2_prod_0.2.1.bin`, etc.)
8+
- Or build your own [on MacOS](macos.md) or [Linux](linux.md)
9+
10+
2. **Put the ESP32 in Bootloader Mode**
11+
12+
If you're already in MicroPythonOS: go to Settings - Restart to Bootloader - Bootloader - Save.
13+
14+
Otherwise, physically keep the "BOOT" (sometimes labeled "START") button pressed while briefly pressing the "RESET" button.
15+
16+
3. **Flash the firmware**
17+
18+
```
19+
~/.espressif/python_env/idf5.2_py3.9_env/bin/python -m esptool --chip esp32s3 0x0 firmware_file.bin
20+
```
21+
22+
Add --erase-all if you want to erase the entire flash memory, so that no old files or apps will remain.
23+
24+
There's also a convenient `./scripts/flash_over_usb.sh` script that will attempt to flash the latest firmware that you compiled yourself.
25+
26+
4. **Access the MicroPython REPL shell**
27+
28+
After reset, the REPL shell should be available on the serial line.
29+
30+
Any serial client will do, but it's convenient to use the `mpremote.py` tool that's shipped with lvgl_micropython:
31+
32+
```
33+
lvgl_micropython/lib/micropython/tools/mpremote/mpremote.py
34+
```
35+
36+
5. **Populate the filesystem** (only for "dev" builds)
37+
38+
The "dev" builds come without a filesystem so you probably want to copy the whole internal_filesystem/ folder over, as well as one of the device-specific boot*.py files and main.py.
39+
40+
There's a convenient script that will do this for you.
41+
42+
Usage:
43+
44+
<pre>
45+
```
46+
./scripts/install.sh <target device>
47+
```
48+
</pre>
49+
50+
**Target devices**: waveshare-esp32-s3-touch-lcd-2 or fri3d-2024
51+
52+
Examples:
53+
54+
<pre>
55+
```
56+
./scripts/install.sh fri3d-2024
57+
./scripts/install.sh waveshare-esp32-s3-touch-lcd-2
58+
```
59+
</pre>
60+
61+
62+
## Notes
63+
64+
- A "dev" build without frozen files is quite a bit slower when starting apps because all the libraries need to be compiled at runtime.
65+
- Ensure your ESP32 is compatible (see [Supported Hardware](../getting-started/supported-hardware.md)). If it's not, then you might need the [Porting Guide](../os-development/porting-guide.md).

‎docs/os-development/linux.md‎

Lines changed: 1 addition & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -21,70 +21,6 @@ sudo apt update
2121
sudo apt-get install -y build-essential libffi-dev pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev fcitx-libs-dev libpipewire-0.3-dev libwayland-dev libdecor-0-dev libv4l-dev
2222
```
2323

24-
## Compile the code
2524

26-
1. **Make sure you're in the main repository**:
2725

28-
```
29-
cd MicroPythonOS
30-
```
31-
32-
2. **Start the Compilation**
33-
34-
Usage:
35-
36-
<pre>
37-
```
38-
./scripts/build_lvgl_micropython.sh <target system> <build type (prod or dev)> [optional target device]
39-
```
40-
</pre>
41-
42-
**Target systems**: esp32, unix (= Linux) and macOS
43-
44-
**Build types**:
45-
46-
- A "prod" build includes the complete filesystem that's "frozen" into the build, so it's fast and all ready to go but the files in /lib and /builtin will be read-only.
47-
- A "dev" build comes without a filesystem, so it's perfect for power users that want to work on MicroPythonOS internals. There's a simple script that will copy all the necessary files over later, and these will be writeable.
48-
49-
_Note_: for unix and macOS systems, only "dev" has been tested. The "prod" builds might have issues but should be made to work soon.
50-
51-
**Target devices**: waveshare-esp32-s3-touch-lcd-2 and fri3d-2024
52-
53-
**Examples**:
54-
55-
<pre>
56-
```
57-
./scripts/build_lvgl_micropython.sh esp32 prod fri3d-2024
58-
./scripts/build_lvgl_micropython.sh esp32 dev waveshare-esp32-s3-touch-lcd-2
59-
./scripts/build_lvgl_micropython.sh esp32 unix dev
60-
./scripts/build_lvgl_micropython.sh esp32 macOS dev
61-
```
62-
</pre>
63-
64-
The resulting build file will be in `lvgl_micropython/build/`, for example:
65-
66-
- lvgl_micropython/build/lvgl_micropy_unix
67-
- lvgl_micropython/build/lvgl_micropy_macOS
68-
- lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-16.bin
69-
70-
## Running on Linux
71-
72-
1. Download a release binary (e.g., `MicroPythonOS_amd64_Linux`) or use your own build from above.
73-
2. Run the application:
74-
75-
<pre>
76-
```
77-
cd internal_filesystem/
78-
/path/to/MicroPythonOS_amd64_Linux -X heapsize=32M -v -i -c "$(cat boot_unix.py main.py)"
79-
```
80-
</pre>
81-
82-
There's also convenient `./scripts/run_desktop.sh` script that will attempt to start the latest build, if you compiled it yourself.
83-
84-
### Modifying files
85-
86-
You'll notice that, whenever you change a file on your local system, the changes are immediately visible whenever you reload the file.
87-
88-
This results in a very quick coding cycle.
89-
90-
Give this a try by editing `internal_filesystem/builtin/apps/com.micropythonos.about/assets/about.py` and then restarting the "About" app. Powerful stuff!
26+
{!os-development/compile-and-run.md!}

‎mkdocs.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ theme:
3131
custom_dir: docs/overrides
3232
extra_css:
3333
- stylesheets/extra.css
34+
markdown_extensions:
35+
- markdown_include.include:
36+
base_path: docs
3437
nav:
3538
- Home: index.md
3639
- Overview: overview.md
@@ -51,7 +54,7 @@ nav:
5154
- On Linux: os-development/linux.md
5255
- On MacOS: os-development/macos.md
5356
- On Windows: os-development/windows.md
54-
- Install on ESP32: os-development/manual-install-esp32.md
57+
- Installing on ESP32: os-development/installing-on-esp32.md
5558
- Porting Guide: os-development/porting-guide.md
5659
- Other:
5760
- Release Process: other/release-checklist.md

0 commit comments

Comments
 (0)