HomeDing WebFiles

Build Status:

This is the project of the HomeDing library related to web technologies. It i used for multiple purposes:

• The Web UI to be embedded into the HomeDing devices is developed using TypeScript and SCSS compilation and packaging. The result is a set of static files that can be uploaded to devices.

• There is a device simulator integrated that allows to use mock files and some mock service implementations that helps developing and testing without the need for flashing physical devices.

• The Portal implementation is as central solution that identifies all HomeDing devices in the local network and offers an easy navigation to the device specific pages.

This project relies on the nodejs runtime and several libraries. See installation.

Overview

The project is not producing a npm library but a distributable solution in 2 variations. Therefore packing and publishing is not used as usual for libraries.

npm tasks in use:

install ---> build ------------+---> start 
              |                |
              +-> build:ts     +--> pack
              +-> build:css          +-> pack:dist
                                     +-> pack:minimal
                                     +-> pack:embed

The build steps create derived version of the source files.

The pack steps create the target file collections.

Installation

To use the project a node.js installation version 12.x or later is required.

• clone the repository to a local folder
• install node.js version 12.x or later
• run npm install to load the dependencies (libraries)

Building

The npm run build will trigger compiling the typescript files and the SASS files into javascript and CSS. The resulting files are not uglified or packed to enable easily debugging.

This is a pre-requisite to start the local server that simulates a device and mocks data. npm start will do a npm run build before actually starting the server.

• build:css: compile iotstyle.scss to iotstyle.css
• build:css-watch: compile iotstyle.scss to iotstyle.css and watch for changes
• build:ts: compile the typescript files to micro.js
• build:ts-watch: compile the typescript files to micro.js and watch for changes
• build: compile typescript and SCSS

Starting the server

The server for the simulation web site uses express web server as a foundation and it can be customized by some command line options.

The simulated type of device is defined by the config and status files in the corresponding sub folder like case-ntp.

The npm start will start the server after building the javascript and CSS files.

To start a specific test case you can add parameters like:

npm start -- -c air

to start the air test case defined in the case-air folder.

The open the default page using http://localhost:3123/ for device simulation.

The start the portal implementation use http://localhost:3123/portal.htm.

Packing

npm run pack

This command will create all packages below.

Packing for standard distributions

The standard pack contains all Web UI files for a full-featured device. This requires a filesystem of min. 1 MByte.

npm run pack:dist

This command will create a dist folder with all files required for upload into the filesystem of a new device.

In this packing job is implemented using a nodejs implementation that you can find in packdist.js. It knows the required files and will copy them (no minifying etc) into the dist folder.

In addition a list.txt file is formed that will also name all the files that can be updated by the built-in boot.htm implementation that can be started using http://[devname]/$boot.htm even on devices that only have a sketch uploaded and still an empty filesystem.

Packing for minimal distributions

The minimal pack contains all Web UI files for a small device. This requires a filesystem of min. 128 kByte.

npm run pack:minimal

This command will create a dist-mini folder with all files required for upload to minimal devices.

In this packing job is implemented using a nodejs implementation that you can find in packminimal.js. It knows the required files and will transfer them into the dist-mini folder. Some files will be minified (HTML, CSS) or uglified (JS) to save space on the filesystem.

In addition a list.txt file is formed that will also name all the files that can be updated by the built-in boot.htm implementation that can be started using http://[devname]/$boot.htm even on devices that only have a sketch uploaded and still an empty filesystem.

You an specify the download version with a parameter ???

Create the builtin web UI

To create the builtin web ui that will be compiled into the firmware the upload.h file can be created by using the script packembedweb.js.

npm run pack:embed

This command will create the upload.h file with the embedded pages for setup

The generated upload.h file needs to be copied to the Arduino library folder.

The source files used are:

• makeembedtemplate.txt
• setup.htm
• upload.htm
• boot.htm

Plugins used

The server and the build tasks are using the following packages:

• express: web server
• debug: logging output
• multer: express middleware for uploading files
• yargs: command line for starting the server
• typescript: compile typescript to javascript
• html-minifier : reduce html file size
• node-sass : compile SCSS to CSS
• uglify-js: minify javascript files
• shell: shell operations of files and folders

See also:

• Use the HomeDing library on a new device: https://homeding.github.io/#page=stepsnewdevice.md
• New upload or upgrade the web on a device: https://homeding.github.io/#page=stepsupdateweb.md