From 5a507db3d36ff6b0df258441086465af026aea48 Mon Sep 17 00:00:00 2001 From: apt105 <73254487+apt105@users.noreply.github.com> Date: Thu, 15 Apr 2021 11:19:53 +0100 Subject: [PATCH 1/4] web-app pages --- website/docs/software/web/config.md | 81 ++++++++++++++++++ website/docs/software/web/development.md | 100 +++++++++++++++++++++++ website/docs/software/web/partitions.md | 57 +++++++++++++ website/docs/software/web/usage.md | 35 ++++++++ website/docs/software/web/web-app.md | 16 ++++ website/sidebars.js | 9 ++ 6 files changed, 298 insertions(+) create mode 100644 website/docs/software/web/config.md create mode 100644 website/docs/software/web/development.md create mode 100644 website/docs/software/web/partitions.md create mode 100644 website/docs/software/web/usage.md create mode 100644 website/docs/software/web/web-app.md diff --git a/website/docs/software/web/config.md b/website/docs/software/web/config.md new file mode 100644 index 00000000..87fdcba3 --- /dev/null +++ b/website/docs/software/web/config.md @@ -0,0 +1,81 @@ +--- +id: web-config-software +title: Initial configuration +sidebar_label: Configuration +--- + +## Manual Installation + +Pre-requisite: You have Meshtastic Device firmware between 1.0.32 - 1.1.50 + +We do realize this installation method is not "easy" and are exploring ways to simplify this in the future, ideally rolling it out as part of the device firmware. + +Once you have your device loaded with the Meshtastic Device firmware you need to connect to it's wifi and then manually upload the Meshtastic Web files. + +### Connect to device wifi + +The easiest way to turn on the device wifi is to do the following after the device has been powered on: + +* Hold down the user button +* Press and release the reset button +* Count to 2 +* Let go of the user button + +:::note +Some devices call this the “prog” button. On devices with two buttons where one is a reset button — it’s usually the other one. On T-beam devices it is the middle button. +::: + +The device will now go into WiFi SoftAP Admin Mode. In this mode, your device will broadcast the following credentials on a built in Access Point: + +* SSID: meshtasticAdmin +* Password: 12345678 + +:::note +The first time your device restarts after enabling WiFi, it will take an additional 20-30 seconds to boot. This is to generate self-signed SSL keys. The keys will be saved for future reuse. +::: + +### Upload Meshtastic-web files + +Next download the three files (app.css.gz, app.js.gz and index.html.gz) from: + +[https://github.com/meshtastic/meshtastic-web/releases](https://github.com/meshtastic/meshtastic-web/releases) + +Then manually upload them to your device by going to: + +* Hostname over mDNS +* * [http://meshtastic.local/static](http://meshtastic.local/static) +* If mDNS doesn't work for you +* * http://{your device IP address here}/static +* * Device IP address typically defaults to 192.168.42.1 + +The Meshtastic-web application can then be accessed by visiting [http://meshtastic.local/](http://meshtastic.local/) or [http://192.168.42.1/](http://192.168.42.1/) + +We do realize this is not "easy" and are exploring ways to simplify this in the future, ideally rolling it out as part of the device firmware. + +### Wifi configuration + +To enable the WiFi to access the Meshtastic Web Interface, you must at minimum set two preferences: + +`wifi_ssid` +`wifi_password` + +For the wifi features to be enabled, those two properties must be set. + +To turn it off, either of preference must be set as an empty string, that is a pair of double quotes each: + +`wifi_ssid ""` +`wifi_password ""` + +Alternatively, you can enable the internal Soft Access Point: + +`wifi_ap_mode true` + +With that enabled, we will broadcast a new wifi network with the SSID and password you set. In AP mode, your device will act as a Captive Portal with a built in DNS server that resolves all name requests back to the device. Additionally, Apple Captive Portal Assistant is implemented -- if you're on an Apple device, the Meshtastic Web Interface will pop up automagically. + +To turn it off, simply reboot the device. + +Right now, the only way to set those preference is through the Meshtastic-python command line tool. At some point, we will be able to configure this from your mobile phone over Bluetooth. + +:::note +The first time your device restarts after enabling WiFi, it will take an additional 20-30 seconds to boot. This is to generate self-signed SSL keys. The keys will be saved for future reuse. +::: diff --git a/website/docs/software/web/development.md b/website/docs/software/web/development.md new file mode 100644 index 00000000..ac79a929 --- /dev/null +++ b/website/docs/software/web/development.md @@ -0,0 +1,100 @@ +--- +id: web-development-software +title: Information for developers of Meshtastic-web +sidebar_label: Development +--- + + +## Considerations + +We have a total of 458752 bytes (448KB) available on the SPIFFS (Serial Peripheral Interface Flash File System) -- the on board storage of the ESP32. Of that space, let's not use more than half of that (224KB) in order to leave space for other uses. + +Right now, the Meshtastic Device Preferences as well as SSL keys use that space. We can imagine other future uses as well such as logging chat messages and possibly saving received signal strength with GPS coordinates to create coverage heat maps. + +## Static Files + +Static files can be placed in the /data folder. All files should be compressed in the .gz format with a .gz extension regardless of the file type. + +As an example, this would mean we will have files such as: + +* style.css.gz +* meshtastic.js.gz +* meshtasticlogo.png.gz + +Unless otherwise stated, files in the `/data` folder of the source code will be stored in `/static` on the device. + +## Application Interface + +We make extensive use of [Meshtastic.js](https://github.com/meshtastic/meshtastic.js). + +## Embedded Server + +### Root + +When requesting to the root of the web server, the either /static/index.html or /static/index.html.gz will be fetched from the file system and served to the client. We require that the file is in the gzip format. Serving an uncompressed file is not supported. If both index.html and index.html.gz are on the filesystem, index.html will be served and index.html.gz will be ignored. + +### /static + +All files stored in /data/static in the Meshtastic source code will be available in /static on the Meshtastic device. + +If a file is uploaded in a .gz format, the .gz extension will be stripped prior to being served to the client. Keep your filenames as short as possible. Short filenames work better than long file names. + +An experimental file system browser with upload and delete capability is available by going to either: + +* http://meshtastic.local/static +* https://meshtastic.local/static + +There are known issues with uploading files with large file sizes. + +The current preferred method to upload data is through PlatformIO and the file system browser is provided without guarantees. + +### /restart + +A post to this location will cause the device to restart. + +### /favicon.ico + +The Meshtastic logo in .ico format. + +### /hotspot-detect.html + +Used by the Apple Captive Portal Assistant. + +### /upload + +End point to upload files. Used by the file manager. + +### /json/report + +Return a report of airtime statistics and current status. + +Formula to calculate when the current time period will roll over: + +`data.airtime.seconds_per_period - (data.airtime.seconds_since_boot % data.airtime.seconds_per_period)` + +### /json/scanNetworks + +Returns a json data structure of WiFi networks in the area. It's recommended to call this at least 2 or 3 times and combine the results. + +We purposely exclude open (insecure) networks from the list. + +### /json/spiffs/browse/static + +Returns a json data structure with the contents of /static. + +If a filename includes a '.gz' extension, will also return a modified version of the filename with the extension stripped. This is to support the functionality in /static (see above). + +### /json/spiffs/delete/static + +Delete file specified by the parameter "delete". Use the method "DELETE". + +eg: /json/spiffs/delete/static?delete=static/something.txt + +### Performance + +As a general guide, the ESP32 will return HTTP requests significantly faster than HTTPS requests. For responses of 1kb or less, expect the following for real world performance: + +HTTP - 3.0 requests / sec +HTTPS - 0.4 requests / sec + +The bottleneck of HTTPS is with the SSL handshake. We will get better performance serving one large file rather than multiple small files. diff --git a/website/docs/software/web/partitions.md b/website/docs/software/web/partitions.md new file mode 100644 index 00000000..969037f0 --- /dev/null +++ b/website/docs/software/web/partitions.md @@ -0,0 +1,57 @@ +--- +id: web-partitions-software +title: Managing ESP32 partitions +sidebar_label: ESP32 partitions +--- + +## Insufficient space to upload Meshtastic web files + +This problem seems to occur when your board has the partitioning structure set incorrectly. This typically occurs when the board has had a firmware other than Meshtastic on it previously. In this situation, the file upload page on the device typically shows a free space of around 48,000 bytes, rather than the ~300,000 bytes that it should have free. + +![Meshtastic.local's upload page showing insufficient storage space](https://raw.githubusercontent.com/meshtastic/Meshtastic-device/master/images/Insufficient%20space.png) + +There are a number of methods that essentially involve erasing the flash and then re-uploading the Meshtastic firmware. + +### Install Script + +The most reliable way to fix this problem is to use the install script that is included in the meshtastic firmware zip. If that doesn’t work, these other methods may work: + +### Alternative methods + +#### Using the Arduino IDE: + +https://meshtastic.discourse.group/t/solved-help-installing-with-other-than-esphome-flasher/2214/9 + +#### Using Pio in Windows +```powershell +pio run --target erase --environment tbeam +``` +Then re-install the firmware ie using ESPHome Flasher + +Requires: [Python](https://www.python.org/), [Pio](https://pypi.org/project/pio/), command to be run in the root directory of the meshtastic-device project once you’ve cloned it (this last requirement is an assumption based on pio not knowing what a tbeam is, may also require Visual Studio Code and PlatformIO as these were installed during use). + +#### Esptool.py +@1984 posted another method using the python based esptool.py to erase and re-flash the firmware: +```bash +esptool.py --baud 921600 erase_flash +esptool.py --baud 921600 write_flash 0x1000 system-info.bin +esptool.py --baud 921600 write_flash 0x00390000 spiffs-*.bin +esptool.py --baud 921600 write_flash 0x10000 firmware-tbeam-EU865-1.1.42.bin +``` + +Requires: [Python](https://www.python.org/) and [esptool.py](https://github.com/espressif/esptool) + +#### Visual Studio & PlatformIO +There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the meshtastic-device code as per the [build instructions](https://github.com/meshtastic/Meshtastic-device/blob/master/docs/software/build-instructions.md). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command. + +![Erasing the flash using PlatformIO in Visual Studio Code](https://raw.githubusercontent.com/meshtastic/Meshtastic-device/master/images/platformio-erase.png) + +https://meshtastic.discourse.group/t/configuring-channel-via-python-api/1948/17 + +Requires: [Visual Studio Code](https://code.visualstudio.com/), [PlatformIO](https://platformio.org/), cloned copy of the Meshtastic-device project + +## How do I know it's worked? + +Once it has been successfully erased and re-flashed, visiting https://192.168.42.1/static should leave you with free space on the order of 300,000 bytes, rather than the ~48,000 bytes you currently have. You can then upload the files from the meshtastic-web release. + +Occasionally this may glitch when uploading the larger app.js.gz file, but a further erase and flash typically solves this. \ No newline at end of file diff --git a/website/docs/software/web/usage.md b/website/docs/software/web/usage.md new file mode 100644 index 00000000..1d421834 --- /dev/null +++ b/website/docs/software/web/usage.md @@ -0,0 +1,35 @@ +--- +id: web-usage-software +title: Using Meshtastic-web +sidebar_label: Usage +--- + +Assuming your device is connected to a wireless network, push the User Button (that's the middle button on the T-Beam) until you get to the Network settings screen. + +That screen will display four lines (example): + +* WiFi: Software AP (Admin) +* IP: 192.168.42.123 (0/4) +* SSID: dogsRuleCatsDrool - alternating with - PWD: butDogsFearCats +* http://meshtastic.local + +If you have just one Meshtastic device on your network, the easiest thing to do is to go the URL printed on the display. That URL should work provided that mDNS (aka ZeroConf) is not blocked on your local network. If you have more than one device or there's a problem with mDNS name resolution, you will have to refer to the device's IP address. + + +## Common Problems + +### Problem: File not found: /static/index.html + +Cause: This most likely means that the file system for the web server has not been loaded. You probably used esphome-flasher or some other GUI tool to flash the firmware. + +Solutions: + +Option 1) Flash the device with the `device-install.sh` script that comes packaged with the firmware zip file (you'll lose previous settings). + +Option 2) Flash the device with the OTA update from within the Android application. + +Option 3) Flash the device with the SPIFFS instructions in platform.io below. + +### Insufficient space to upload new files + +Cause: Typically a small partition has been set aside from previous firmware installed on the module. Instructions for how to fix this can be found on the [ESP32-Partitions](/docs/software/web/web-partitions-software) page. diff --git a/website/docs/software/web/web-app.md b/website/docs/software/web/web-app.md new file mode 100644 index 00000000..c56c1ca8 --- /dev/null +++ b/website/docs/software/web/web-app.md @@ -0,0 +1,16 @@ +--- +id: web-app-software +title: Meshtastic-web overview +sidebar_label: Overview +--- + +The Meshtastic firmware incorporates an embedded webserver using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the wifi supporting ESP32 devices to run our Meshtastic-web application to deliver a native web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/js/getting-started) to provide a web page capable of interacting with the device. + +:::caution +Please note that this is under active development and liable to change +::: + +:::warning +The current Meshtastic-web depolyment only works with the 1.1.x versions of the device firmware. Support for 1.2.x will hopefully arrive soon +::: + diff --git a/website/sidebars.js b/website/sidebars.js index e66a1d55..9b5648b9 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -45,6 +45,15 @@ module.exports = { "software/plugins/environment-plugin", ], }, + { + "Meshtastic-web": [ + "software/web/web-app-software", + "software/web/web-config-software", + "software/web/web-usage-software", + "software/web/web-partitions-software", + "software/web/web-development-software", + ], + }, { Other: [ "software/other/sw-design", From 03ccf8e301622e770a4d09cdef951707b91b8fe0 Mon Sep 17 00:00:00 2001 From: apt105 <73254487+apt105@users.noreply.github.com> Date: Thu, 15 Apr 2021 11:21:20 +0100 Subject: [PATCH 2/4] Update web-app.md --- website/docs/software/web/web-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/software/web/web-app.md b/website/docs/software/web/web-app.md index c56c1ca8..2f3cb05d 100644 --- a/website/docs/software/web/web-app.md +++ b/website/docs/software/web/web-app.md @@ -4,7 +4,7 @@ title: Meshtastic-web overview sidebar_label: Overview --- -The Meshtastic firmware incorporates an embedded webserver using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the wifi supporting ESP32 devices to run our Meshtastic-web application to deliver a native web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/js/getting-started) to provide a web page capable of interacting with the device. +The Meshtastic firmware incorporates an embedded webserver using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the wifi supporting ESP32 devices to run our Meshtastic-web application to deliver a native web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/software/js/getting-started) to provide a web page capable of interacting with the device. :::caution Please note that this is under active development and liable to change From 50cd94fcc623742d95078212878661e2bc16355a Mon Sep 17 00:00:00 2001 From: apt105 <73254487+apt105@users.noreply.github.com> Date: Thu, 15 Apr 2021 12:55:19 +0100 Subject: [PATCH 3/4] Change Meshtastic-web to web interface --- website/docs/software/web/config.md | 6 +++--- website/docs/software/web/development.md | 2 +- website/docs/software/web/partitions.md | 2 +- website/docs/software/web/usage.md | 2 +- website/docs/software/web/web-app.md | 9 ++------- website/sidebars.js | 2 +- 6 files changed, 9 insertions(+), 14 deletions(-) diff --git a/website/docs/software/web/config.md b/website/docs/software/web/config.md index 87fdcba3..67698dcb 100644 --- a/website/docs/software/web/config.md +++ b/website/docs/software/web/config.md @@ -6,7 +6,7 @@ sidebar_label: Configuration ## Manual Installation -Pre-requisite: You have Meshtastic Device firmware between 1.0.32 - 1.1.50 +Pre-requisite: You have Meshtastic Device firmware between version 1.0.32 - 1.1.50. A client for version 1.2.x will be released shortly and the documentation update accordingly. We do realize this installation method is not "easy" and are exploring ways to simplify this in the future, ideally rolling it out as part of the device firmware. @@ -34,7 +34,7 @@ The device will now go into WiFi SoftAP Admin Mode. In this mode, your device wi The first time your device restarts after enabling WiFi, it will take an additional 20-30 seconds to boot. This is to generate self-signed SSL keys. The keys will be saved for future reuse. ::: -### Upload Meshtastic-web files +### Upload web interface files Next download the three files (app.css.gz, app.js.gz and index.html.gz) from: @@ -48,7 +48,7 @@ Then manually upload them to your device by going to: * * http://{your device IP address here}/static * * Device IP address typically defaults to 192.168.42.1 -The Meshtastic-web application can then be accessed by visiting [http://meshtastic.local/](http://meshtastic.local/) or [http://192.168.42.1/](http://192.168.42.1/) +The web interface application can then be accessed by visiting [http://meshtastic.local/](http://meshtastic.local/) or [http://192.168.42.1/](http://192.168.42.1/) We do realize this is not "easy" and are exploring ways to simplify this in the future, ideally rolling it out as part of the device firmware. diff --git a/website/docs/software/web/development.md b/website/docs/software/web/development.md index ac79a929..e154b654 100644 --- a/website/docs/software/web/development.md +++ b/website/docs/software/web/development.md @@ -1,6 +1,6 @@ --- id: web-development-software -title: Information for developers of Meshtastic-web +title: Information for developers of the web interface sidebar_label: Development --- diff --git a/website/docs/software/web/partitions.md b/website/docs/software/web/partitions.md index 969037f0..add001b4 100644 --- a/website/docs/software/web/partitions.md +++ b/website/docs/software/web/partitions.md @@ -4,7 +4,7 @@ title: Managing ESP32 partitions sidebar_label: ESP32 partitions --- -## Insufficient space to upload Meshtastic web files +## Insufficient space to upload web interface files This problem seems to occur when your board has the partitioning structure set incorrectly. This typically occurs when the board has had a firmware other than Meshtastic on it previously. In this situation, the file upload page on the device typically shows a free space of around 48,000 bytes, rather than the ~300,000 bytes that it should have free. diff --git a/website/docs/software/web/usage.md b/website/docs/software/web/usage.md index 1d421834..ab589a67 100644 --- a/website/docs/software/web/usage.md +++ b/website/docs/software/web/usage.md @@ -1,6 +1,6 @@ --- id: web-usage-software -title: Using Meshtastic-web +title: Using the web interface sidebar_label: Usage --- diff --git a/website/docs/software/web/web-app.md b/website/docs/software/web/web-app.md index 2f3cb05d..2eb2b705 100644 --- a/website/docs/software/web/web-app.md +++ b/website/docs/software/web/web-app.md @@ -1,16 +1,11 @@ --- id: web-app-software -title: Meshtastic-web overview +title: Web interface overview sidebar_label: Overview --- -The Meshtastic firmware incorporates an embedded webserver using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the wifi supporting ESP32 devices to run our Meshtastic-web application to deliver a native web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/software/js/getting-started) to provide a web page capable of interacting with the device. +The Meshtastic firmware incorporates an embedded webserver using the [ESP32 HTTPS Server](https://github.com/fhessel/esp32_https_server) project. This allows the wifi supporting ESP32 devices to run our web interface to access Meshtastic directly from your browser. This imports the [Meshtastic.js library](/docs/software/js/getting-started) to provide a web page capable of interacting with the device. :::caution Please note that this is under active development and liable to change ::: - -:::warning -The current Meshtastic-web depolyment only works with the 1.1.x versions of the device firmware. Support for 1.2.x will hopefully arrive soon -::: - diff --git a/website/sidebars.js b/website/sidebars.js index 9b5648b9..4a7808da 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -46,7 +46,7 @@ module.exports = { ], }, { - "Meshtastic-web": [ + "Web interface": [ "software/web/web-app-software", "software/web/web-config-software", "software/web/web-usage-software", From 0f69cca917926a2858d4075f38c2b19094529106 Mon Sep 17 00:00:00 2001 From: apt105 <73254487+apt105@users.noreply.github.com> Date: Thu, 15 Apr 2021 13:01:22 +0100 Subject: [PATCH 4/4] catch further meshtastic-web mentions --- website/docs/software/web/config.md | 8 ++++---- website/docs/software/web/usage.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/website/docs/software/web/config.md b/website/docs/software/web/config.md index 67698dcb..9ffb6d18 100644 --- a/website/docs/software/web/config.md +++ b/website/docs/software/web/config.md @@ -6,11 +6,11 @@ sidebar_label: Configuration ## Manual Installation -Pre-requisite: You have Meshtastic Device firmware between version 1.0.32 - 1.1.50. A client for version 1.2.x will be released shortly and the documentation update accordingly. +Pre-requisite: You have Meshtastic Device firmware between version 1.0.32 - 1.1.50. A client for version 1.2.x will be released shortly and the documentation will be updated accordingly. We do realize this installation method is not "easy" and are exploring ways to simplify this in the future, ideally rolling it out as part of the device firmware. -Once you have your device loaded with the Meshtastic Device firmware you need to connect to it's wifi and then manually upload the Meshtastic Web files. +Once you have your device loaded with the Meshtastic Device firmware you need to connect to it's wifi and then manually upload the web interface files. ### Connect to device wifi @@ -54,7 +54,7 @@ We do realize this is not "easy" and are exploring ways to simplify this in the ### Wifi configuration -To enable the WiFi to access the Meshtastic Web Interface, you must at minimum set two preferences: +To enable the WiFi to access the web interface, you must at minimum set two preferences: `wifi_ssid` `wifi_password` @@ -70,7 +70,7 @@ Alternatively, you can enable the internal Soft Access Point: `wifi_ap_mode true` -With that enabled, we will broadcast a new wifi network with the SSID and password you set. In AP mode, your device will act as a Captive Portal with a built in DNS server that resolves all name requests back to the device. Additionally, Apple Captive Portal Assistant is implemented -- if you're on an Apple device, the Meshtastic Web Interface will pop up automagically. +With that enabled, we will broadcast a new wifi network with the SSID and password you set. In AP mode, your device will act as a Captive Portal with a built in DNS server that resolves all name requests back to the device. Additionally, Apple Captive Portal Assistant is implemented -- if you're on an Apple device, the web interface will pop up automagically. To turn it off, simply reboot the device. diff --git a/website/docs/software/web/usage.md b/website/docs/software/web/usage.md index ab589a67..e0a55eaa 100644 --- a/website/docs/software/web/usage.md +++ b/website/docs/software/web/usage.md @@ -24,11 +24,11 @@ Cause: This most likely means that the file system for the web server has not be Solutions: -Option 1) Flash the device with the `device-install.sh` script that comes packaged with the firmware zip file (you'll lose previous settings). +Option 1) Flash the device with the `device-install.sh` script that comes packaged with the firmware zip file (you'll lose previous settings). Then follow the instructions under configuration to upload the web interface Option 2) Flash the device with the OTA update from within the Android application. -Option 3) Flash the device with the SPIFFS instructions in platform.io below. +Option 3) Flash the device with the SPIFFS instructions in platform.io. ### Insufficient space to upload new files