Skip to content

Commit 1098b99

Browse files
rjwatsrjwats
committed
WIP readme
1 parent e66deb9 commit 1098b99

File tree

2 files changed

+84
-60
lines changed

2 files changed

+84
-60
lines changed

‎README.md

+84-60
Original file line numberDiff line numberDiff line change
@@ -30,28 +30,44 @@ You will need the following before you can get started.
3030
* [Node.js](https://nodejs.org) - For building the interface with npm
3131
* Bash shell, or [Git Bash](https://gitforwindows.org/) if you are under windows
3232

33-
### Building in PlatformIO
33+
### Building and uploading the firmware
3434

3535
Pull the project and open it in PlatformIO. PlatformIO should download the ESP8266 platform and the project library dependencies automatically.
3636

37-
The project directory structure is as follows:
37+
The project structure is as follows:
3838

39-
Directory | Description
39+
Resource | Description
4040
---- | -----------
4141
[data/](data) | The file system image directory
4242
[interface/](interface) | React based front end
4343
[src/](src) | C++ back end for the ESP8266 device
4444
[platformio.ini](platformio.ini) | PlatformIO project configuration file
4545

46+
#### Building the firmware
47+
4648
Once the platform and libraries are downloaded the back end should be compiling.
4749

4850
> **WINDOWS BUILDS**: If building under Windows you need to delete .piolibdeps/Time/Time.h - due to a [file system case insensitivity issue](https://github.com/me-no-dev/ESPAsyncWebServer/issues/96)
4951
52+
#### Uploading the firmware
53+
54+
Standard configuration settings, such as build flags, libraries and device configuration can be found in ['platformio.ini'](platformio.ini). The project is configured to upload via serial by default, you can change the upload mechanism to OTA by uncommenting the relevant lines.
55+
56+
See the [PlatformIO docs](http://docs.platformio.org/en/latest/projectconf.html) for full details on what you can do with this.
57+
58+
Click the upload button in PlatformIO, or type the upload command if prefer the command line approach:
59+
60+
```bash
61+
platformio run -t upload
62+
```
63+
64+
![upload](/media/upload.png?raw=true "upload")
65+
5066
### Building the interface
5167

52-
The interface has been configured with create-react-app and react-app-rewired so the build can customized for the target device. The large artefacts are gzipped and source maps and service worker are excluded from the production build.
68+
The interface has been configured with create-react-app and react-app-rewired so the build can customized for the target device. The large artefacts are gzipped and source maps and service worker are excluded from the production build. This reduces the production build to around ~200k, which easily fits on the device.
5369

54-
Change to this directory with your bash shell (or Git Bash) and use the standard commands you would with any react app built with create-react-app:
70+
Change to the ['interface'](interface) directory with your bash shell (or Git Bash) and use the standard commands you would with any react app built with create-react-app:
5571

5672
#### Change to interface directory
5773

@@ -73,31 +89,85 @@ npm run build
7389

7490
> **Note**: The build command will also delete the previously built interface, in the ['data/www'](data/www) directory, replacing it with the freshly built one ready to upload to the device.
7591
76-
#### Running the interface locally
92+
### Running the interface locally
7793

78-
You can run a local development server during development to preview changes to the front end them without uploading a file system image to the device.
94+
You can run a local development server during development to preview changes to the front end them without the need to upload a file system image to the device after each change.
7995

8096
```bash
8197
npm start
8298
```
8399

84100
> **Note**: To run the interface locally you will need to modify the endpoint root path and enable CORS.
85101
86-
The endpoint root path can be found in .env.development, defined as the environment variable 'REACT_APP_ENDPOINT_ROOT'. This needs to be the root URL of the device running the back end, for example:
102+
#### Changing the endpoint root
103+
104+
The endpoint root path can be found in ['interface/.env.development'](interface/.env.development), defined as the environment variable 'REACT_APP_ENDPOINT_ROOT'. This needs to be the root URL of the device running the back end, for example:
87105

88106
```js
89107
REACT_APP_ENDPOINT_ROOT=http://192.168.0.6/rest/
90108
```
91109

92-
CORS can be enabled on the back end by uncommenting the -D ENABLE_CORS build flag in platformio.ini and re-deploying.
110+
#### Enabling CORS
111+
112+
You can enable CORS on the back end by uncommenting the -D ENABLE_CORS build flag in ['platformio.ini'](platformio.ini) then re-building and uploading the firmware to the device. The default settings assume you will be accessing the development server on the default port on [http://localhost:3000](http://localhost:3000) this can also be changed if required:
113+
114+
```
115+
-D ENABLE_CORS
116+
-D CORS_ORIGIN=\"http://localhost:3000\"
117+
```
118+
119+
## Device Configuration
120+
121+
As well as containing the interface, the SPIFFS image (in the ['data'](data) folder) contains a JSON settings file for each of the configurable features. The config files can be found in the ['data/config'](data/config) directory:
122+
123+
File | Description
124+
---- | -----------
125+
[apSettings.json](data/config/apSettings.json) | Access point settings
126+
[ntpSettings.json](data/config/ntpSettings.json) | NTP synchronization settings
127+
[otaSettings.json](data/config/otaSettings.json) | OTA update configuration
128+
[securitySettings.json](data/config/securitySettings.json) | Security settings and user credentials
129+
[wifiSettings.json](data/config/wifiSettings.json) | WiFi connection settings
130+
131+
The default settings configure the device to bring up an access point on start up which can be used to configure the device:
132+
133+
* SSID: ESP8266-React
134+
* Password: esp-react
135+
136+
### Building for different devices
137+
138+
This project supports ESP8266 and ESP32 platforms. To support OTA programming, enough free space to upload the new sketch and file system image will be required. It is recommended that a board with at least 2mb of flash is used.
139+
140+
By default, the target device is "esp12e". This is a common ESP8266 variant with 4mb of flash:
141+
142+
![ESP12E](/media/esp12e.jpg?raw=true "ESP12E")
143+
144+
The settings file ['platformio.ini'](platformio.ini) configures the platform and board:
145+
146+
```
147+
[env:esp12e]
148+
platform = espressif8266
149+
board = esp12e
150+
```
151+
152+
If you want to build for an ESP32 device, all you need to do is re-configure ['platformio.ini'](platformio.ini) with your devices settings.
153+
154+
![ESP32](/media/esp32.jpg?raw=true "ESP32")
155+
156+
Building for the common esp32 "node32s" board for example requires the following configuration:
157+
158+
```
159+
[env:node32s]
160+
platform = espressif32
161+
board = node32s
162+
```
93163

94164
## Customizing and theming
95165

96166
The framework, and MaterialUI allows for a good degree of custoimzation with little effort.
97167

98168
### Theming the app
99169

100-
The app can be easily themed by editing the [MaterialUI theme](https://material-ui.com/customization/themes/). Edit the theme in ./interface/src/App.js as you desire:
170+
The app can be easily themed by editing the [MaterialUI theme](https://material-ui.com/customization/themes/). Edit the theme in ['interface/src/App.js'](interface/src/App.js) as you desire:
101171

102172
```js
103173
const theme = createMuiTheme({
@@ -114,18 +184,18 @@ const theme = createMuiTheme({
114184

115185
### Changing the app icon
116186

117-
You can replace the app icon is located at [./interface/public/app/icon.png](interface/public/app/icon.png) with one of your preference. A 256 x 256 PNG is recommended for best compatibility.
187+
You can replace the app icon is located at ['interface/public/app/icon.png'](interface/public/app/icon.png) with one of your preference. A 256 x 256 PNG is recommended for best compatibility.
118188

119189

120190
### Changing the app name
121191

122-
The app name displayed on the login page and on the menu bar can be modified by editing the REACT_APP_NAME property in [./interface/.env](interface/.env)
192+
The app name displayed on the login page and on the menu bar can be modified by editing the REACT_APP_NAME property in ['interface/.env'](interface/.env)
123193

124194
```js
125195
REACT_APP_NAME=Funky IoT Project
126196
```
127197

128-
There is also a manifest file which contains the app name to use when adding the app to a mobile device, so you may wish to also edit [./interface/public/app/manifest.json](interface/public/app/manifest.json):
198+
There is also a manifest file which contains the app name to use when adding the app to a mobile device, so you may wish to also edit ['interface/public/app/manifest.json'](interface/public/app/manifest.json):
129199

130200
```json
131201
{
@@ -142,55 +212,9 @@ There is also a manifest file which contains the app name to use when adding the
142212
}
143213
```
144214

145-
## Building for different devices
146215

147-
This project supports ESP8266 and ESP32 platforms. To support OTA programming, enough free space to upload the new sketch and file system image will be required. It is recommended that a board with at least 2mb of flash is used.
148216

149-
By default, the target device is "esp12e". This is a common ESP8266 variant with 4mb of flash:
150-
151-
![ESP12E](/media/esp12e.jpg?raw=true "ESP12E")
152-
153-
The settings file platformio.ini configures the platform and board:
154-
155-
```
156-
[env:esp12e]
157-
platform = espressif8266
158-
board = esp12e
159-
```
160-
161-
If you want to build for an ESP32 device, all you need to do is re-configure playformio.ini with your devices settings.
162-
163-
![ESP32](/media/esp32.jpg?raw=true "ESP32")
164-
165-
Building for the common esp32 "node32s" board for example requires the following configuration:
166-
167-
```
168-
[env:node32s]
169-
platform = espressif32
170-
board = node32s
171-
```
172-
173-
## Configuration & Deployment
174-
175-
Standard configuration settings, such as build flags, libraries and device configuration can be found in platformio.ini. See the [PlatformIO docs](http://docs.platformio.org/en/latest/projectconf.html) for full details on what you can do with this.
176-
177-
***** TODO ******
178-
The project is configured to upload via serial by default, you can change the upload mechanism to OTA by uncommenting the relevant lines.
179-
180-
As well as containing the interface, the SPIFFS image (in the ./data folder) contains a JSON settings file for each of the configurable features. The config files can be found in the ./data/config directory:
181-
182-
File | Description
183-
---- | -----------
184-
apSettings.json | Access point settings
185-
ntpSettings.json | NTP synchronization settings
186-
otaSettings.json | OTA update configuration
187-
securitySettings.json | Security settings and user credentials
188-
wifiSettings.json | WiFi connection settings
189-
190-
The default settings configure the device to bring up an access point on start up which can be used to configure the device:
191-
192-
* SSID: ESP8266-React
193-
* Password: esp-react
217+
*******
194218

195219
## Software Overview
196220

‎media/upload.png

12.2 KB
Loading

0 commit comments

Comments
 (0)