Skip to content

Commit 8d0d5bc

Browse files
ewowiewowi
committed
Update develop docs
1 parent 3b08eda commit 8d0d5bc

File tree

6 files changed

+191
-175
lines changed

6 files changed

+191
-175
lines changed

‎docs/develop/development.md‎

Lines changed: 76 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,27 @@
11

22
# Development
33

4-
## Developing
4+
## Summary
55

6-
* Read the [ESP32 Sveltekit docs](https://moonmodules.org/MoonLight/esp32sveltekit/)
7-
* Read [Customizing Sveltekit](https://moonmodules.org/MoonLight/develop/customizingsveltekit/)
8-
* Create a fork so you have your own environment to make changes to. See also Pull Requests below.
9-
* Changes made to the UI are not always visible in the browser, clear the browser cache to see latest UI (see [connect to MoonLight](https://moonmodules.org/MoonLight/gettingstarted/installation/#connect-moonlight)).
10-
* Serial Log shows which code is from which library using emoji:
6+
* Create a branch
7+
* Make changes
8+
* Document your change
9+
* Submit a pull request
1110

12-
<img width="500" alt="Screenshot 2025-06-07 at 12 09 06" src="https://github.com/user-attachments/assets/9ac673d3-6303-40ee-b2a0-26a0befbda01" />
11+
## Create a branch
1312

14-
* 🐼: ESP-SvelteKit
15-
* 🔮: PsychicHTTP
16-
* 🐸: Live Scripts
17-
* 🌙: MoonBase
18-
* 💫: MoonLight
19-
🌙 and 💫 is also used in code comments of ESP32-SvelteKit to show where changes to upstream have been made.
20-
* The following ESP32-SvelteKit features have been switched off in the default builts (they can be switched on if you want to use them, see [features.ini](https://github.com/MoonModules/MoonLight/blob/main/features.ini))
21-
* -D FT_SECURITY=0
22-
* ~~-D FT_SLEEP=1~~ enabled!
23-
* ~~-D FT_BATTERY=1~~ enabled!
24-
25-
## Where you can help
26-
27-
* Improve the web installer
28-
* Improve the UI (Svelte 5, DaisyUI 5, TailWind 4)
29-
* Mutli row layout
30-
* Tune FastLED, add FastLED 2D effects
31-
* CI automation (Generate daily builds in Github and use by installer)
32-
* Palettes: more, custom, audio reactive
13+
* Want to make changes: fork the repo (see installation)and submit pull requests, see [creating-a-pull-request-from-a-fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork):
3314

34-
Contact us in the MoonLight channels on [Discord MoonModules](https://discord.gg/TC8NSUSCdV)
35-
36-
## Pull Requests
37-
38-
* Want to make changes: fork the repo and submit pull requests, see [creating-a-pull-request-from-a-fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork):
39-
40-
* Login to your own github account
41-
* Fork: go to [MoonModules/MoonLight](https://github.com/MoonModules/MoonLight/) and press Fork, uncheck 'Copy the main branch only' and press Create Fork. You will be moved to your fork of MoonLight
4215
* Press Branches, press New Branch, give it a name e.g. background-script and press Create new Branch, click on background-script
4316

4417
<img width="90" src="https://github.com/user-attachments/assets/588d0854-bac1-4b70-8931-ba6db4c94248" />
4518

46-
* Go to the file you want to change press edit and make the changes. E.g. change executable.execute("main") to executable.executeAsTask("main")
47-
* Press Commit Changes..., enter a commit message and an extended description, Press Commit Changes
48-
* Go back to the homepage of your fork [myfork/MoonLight](https://github.com/ewoudwijma/MoonLight). There is a message inviting to create a Pull Request. Press Compare & pull request.
49-
50-
<img width="350" alt="Screenshot 2025-04-15 at 14 59 15" src="https://github.com/user-attachments/assets/410aa517-99eb-4907-b1a3-db7f38abb194" />
51-
52-
* Add a title and Description to the Pull Request and press Create Pull Request
53-
54-
* The upstream MoonLight repo can now process this PR
55-
56-
## Adding functionality
57-
58-
* lib folder for Sveltekit back end
59-
* src folder for MoonBase and MoonLight back end
60-
* interface folder for front end development
61-
* interface/src/routes/moonbase for MoonBase and MoonLight (modules)
62-
63-
64-
* ☑️ and ➡️ to build and or upload
19+
## Make changes
6520

6621
### Front End (UI)
67-
🚧
6822

6923
* interface folder
24+
* interface/src/routes/moonbase for MoonBase and MoonLight (modules)
7025
* see [Prepare for development](https://moonmodules.org/MoonLight/develop/installation/#prepare-for-development) about nodejs, npm install
7126

7227
```
@@ -81,44 +36,85 @@ npm run dev
8136
There are 3 levels to add functionality:
8237

8338
* **Standard ESP32-Sveltekit code**, e.g. Connections, Wifi and System. MoonBase files is also made using standard sveltekit as example but contains a few components used in MoonLight modules. Might be rewriteen as MoonLight Module in the future.
39+
* lib folder for Sveltekit back end
40+
* Read the [ESP32 Sveltekit docs](https://moonmodules.org/MoonLight/esp32sveltekit/)
8441
* [MoonLight Modules](https://moonmodules.org/MoonLight/moonbase/modules/) e.g. Lights Control, Effects, Info, Channels. They are subclasses of Modules.h/cpp and implement setupDefinition, onUpdate and optional loop. New modules need to be defined in main.cpp and added to menu.svelte. All further UI is generated by Module.svelte.
42+
* src folder for MoonBase and MoonLight back end
8543
* **MoonLight Nodes**: the easiest and recommended way. See Effects.h, Layouts.h, Modifiers.h and Drivers.h for examples. They match closest WLED usermods. Each node has controls, a setup and a loop and can be switched on and off. For specific purposes hasOnLayout() and hasModifier() can return true.
44+
* src/MoonLight/nodes
8645

87-
### Adding an ESP32 device Definition
46+
### Steps
8847

89-
Before starting, ensure you have the datasheet of your particular chip and ESP32-device confirmed and available. Many modules have near-identical markings that can hide varying hardware.
48+
* Go to the file(s) you want to change press edit and make the changes.
49+
* ☑️ and ➡️ to build and or upload
50+
* Changes made to the UI are not always visible in the browser, clear the browser cache to see latest UI (see [connect to MoonLight](https://moonmodules.org/MoonLight/gettingstarted/installation/#connect-moonlight)).
51+
* update the documentation (MoonLight has the documentation in the same repo)
52+
* Press Commit Changes..., enter a commit message and an extended description, Press Commit Changes
9053

91-
There are 3 files to consider when making a ESP32-device definition.
54+
## Submit a pull request
9255

93-
boards/BOARD_NAME.csv
94-
boards/BOARD_NAME.JSON
95-
firmware/BOARD_TYPE_NAME.ini (e.g. esp32dev, esp32-s3), contains different boards
56+
* Go back to the homepage of your fork [myfork/MoonLight](https://github.com/ewoudwijma/MoonLight). There is a message inviting to create a Pull Request. Press Compare & pull request.
57+
58+
<img width="350" alt="Screenshot 2025-04-15 at 14 59 15" src="https://github.com/user-attachments/assets/410aa517-99eb-4907-b1a3-db7f38abb194" />
59+
60+
* Add a title and Description to the Pull Request and press Create Pull Request
61+
62+
* The upstream MoonLight repo can now process this PR
9663

97-
### Technical notes
64+
## Addtional info
9865

99-
#### LED drivers
100-
* Switch off to see the effect framerate in System Status/Metrics
101-
* Switch on to see the effect framerate throttled by a LED driver in System Status/Metrics (800KHz, 256 LEDs, 24 bits is 130 fps theoretically - 120 practically)
66+
### Emoji coding
10267

103-
#### Live Scripts
68+
* Serial Log shows which code is from which library using emoji:
10469

105-
* Uses ESPLiveScripts, see compileAndRun. compileAndRun is started when in Nodes a file.sc is choosen
106-
* To do: kill running scripts, e.g. when changing effects
70+
<img width="500" alt="Screenshot 2025-06-07 at 12 09 06" src="https://github.com/user-attachments/assets/9ac673d3-6303-40ee-b2a0-26a0befbda01" />
10771

108-
#### File Manager
72+
* 🐼: ESP-SvelteKit
73+
* 🔮: PsychicHTTP
74+
* 🐸: Live Scripts
75+
* 🌙: MoonBase
76+
* 💫: MoonLight
77+
🌙 and 💫 is also used in code comments of ESP32-SvelteKit to show where changes to upstream have been made.
78+
* The following ESP32-SvelteKit features have been switched off in the default builts (they can be switched on if you want to use them, see [features.ini](https://github.com/MoonModules/MoonLight/blob/main/features.ini))
79+
* -D FT_SECURITY=0
80+
* ~~-D FT_SLEEP=1~~ enabled!
81+
* ~~-D FT_BATTERY=1~~ enabled!
82+
83+
### UI development server
84+
85+
To ease the frontend development you can deploy the back end code on an ESP32 board and pass the websocket and REST API calls through the development server's proxy running on your computer.
86+
87+
This very much speeds up UI development as no flashing to ESP32 is required to test updated UI. Svaing an UI file is enough to see the results!!!
88+
89+
See [Setup Proxy for Development](https://moonmodules.org/MoonLight/gettingstarted/#setup-proxy-for-development) and [development-server](https://moonmodules.org/MoonLight/gettingstarted/#development-server) how to setup.
90+
91+
!!! tip "nodejs"
92+
if nodejs is not installed yet: see [Prepare for development](https://moonmodules.org/MoonLight/develop/installation/#prepare-for-development) to install nodejs
93+
94+
After configuring the development server, a local webserver starts on [localhost:5173](http://localhost:5173/).
95+
96+
### Release and merged firmware binaries
10997

110-
## Technical
98+
Firmware binaries come in 2 flavours: including boot and partition (merged) and MoonLight code only (release). They are stored in the build folder of the MoonLight repo and updated each time a build or upload (☑️ or ➡️) is done. Subfolder merged contains the first type, release the second type.
11199

112-
* filesState: all files on FS
113-
* folderList: all files in a folder
114-
* editableFile: current file
115-
* getState / postFilesState: get filesState and post changes to files (update, delete, new)
116-
* addFile / addFolder: create new items
117-
* breadcrumbs(String): folder path as string array and as string, stored in localStorage
118-
* folderListFromBreadCrumbs: create folderList of current folder
119-
* handleEdit: when edit button pressed: navigate back and forward through folders, edit current file
120-
* confirmDelete: when delete button pressed
121-
* socket files / handleFileState (->folderListFromBreadCrumbs)
100+
* Merged bins are used by the web installer, release bins by the [System update](https://moonmodules.org/MoonLight/system/update/) module (OTA). System update uses the bins stored in [GitHub releases](https://github.com/MoonModules/MoonLight/releases).
101+
* Merged bins starts flashing on address 0x0, release bins on address 0x10000.
102+
* All MoonLight partition schemes have a firmware size of 3MB. Smaller devices (e.g. ESP32-D0) have no OTA partition. System update is possible in this situation, but there is no fallback if update fails (need to flash using USB in that case) 🚧
122103

123-
Using component FileEdit, see [Components](https://moonmodules.org/MoonLight/components/#fileedit)
104+
!!! tip "flash firmware using esptool"
105+
* [>_] in the statusbar of vscode
106+
```
107+
esptool --port /dev/cu.usbmodem11201 write-flash 0x0 ./build/merged/MoonLight_esp32-s3-devkitc-1-n16r8v_0-5-9-3_webflash.bin
108+
```
109+
* optionally add erase-flash before write-flash
110+
* use ./build/release/MoonLight_esp32-s3-devkitc-1-n16r8v_0-5-9-3.bin and address 0x10000 to flash only the MoonLight partition
124111

112+
### Adding an ESP32 device Definition
113+
114+
Before starting, ensure you have the datasheet of your particular chip and ESP32-device confirmed and available. Many modules have near-identical markings that can hide varying hardware.
115+
116+
There are 3 files to consider when making a ESP32-device definition.
117+
118+
boards/BOARD_NAME.csv
119+
boards/BOARD_NAME.JSON
120+
firmware/BOARD_TYPE_NAME.ini (e.g. esp32dev, esp32-s3), contains different boards

0 commit comments

Comments
 (0)