Stairs/DEVELOPING.md

Stairs

This Stairs firmware was developed using PlatformIO Core. You can probably use the PlatformIO IDE as well, although I have no experience using it, so this guide will only use the command line tools.

Programming the ESP8266

You can either use an ESP8266 module with built-in USB like the Wemos D1, a programming fixture (my method of choice, search for "esp8266 fixture" on Google or AliExpress) or wire it up yourself using a CH340 or FTDI USB-to-serial module.

To upload the code, open a console, go to the Stairs folder and run:

platformio run -t upload

It should auto-detect the USB COM port.

Frontend development

The frontend is compiled into C++ source files so that all the files can be served directly from the ESP8266, since there is no internet connection when running in access point mode. These steps are performed by a Gulp script. The Gulp script also updates the version based on the GitVersion of the working copy.

Note that GitVersion requires Windows, so some changes are probably required if you want to build on a different platform.

To get started:

1. Install Node.js
2. Install the GitVersion command line tool
3. Open a command line and navigate to the Stairs folder
4. Run npm update to install all the dependencies

Compiling the assets

Run gulp to compile the SASS files, and embed the CSS, JavaScript, images and HTML into C++ header files located in the src\assets folder.

You may need to run npm install -g gulp to install Gulp into the global Node packages.

Development server

To make it easier to develop the frontend, a development server is included which serves the webpages and acts as a mock service for the API.

To start the development server, run:

node devserver.js

You can now open the frontend on http://localhost:3000/.

If you make any changes to the SCSS files, make sure to run gulp compileSass and gulp compileJS to update the CSS/JS files so your changes are visible in the development server. To keep gulp running and watch for changes in the SCSS and JS files, run gulp watch

Building and/or uploading

To rebuild all the assets and compile or upload the source in one go, two tasks have been added to the gulpfile.js:

1. gulp build first runs all the tasks run by a regular gulp, then builds the source code using platformio run
2. gulp upload is similar, but executes platformio run -t upload to directly upload the newly compiled source to the ESP8266

version.h

The version.h file is generated based on the current GitVersion, which means it changes if you build again right after committing, which causes a change that needs to be committed... did you mean: recursion? The best way I found to deal with this is commit your changes, build, then amend the commit with the updated version.h before pushing the changes. This ensures the version.h is in sync when cloning the repository.