This document summarizes the development decisions and workflows in order to guide developers on how to setup the project themselves.
There are the following sections:
- Quick Start: Local setup, running and building
- Utilized Tools: List containing all used tools
- Overall Design Considerations NPM script documentation
- Folder Structure
- Data Flow
- Known Issues
1. Development Environment Setup
Navigate to the repo folder and open the CLI of your choice to run:
This installs all the dependencies (including devDependencies) from the package.json .
Running the project takes just one command (well, one npm command):
This starts docsify, which serves your documentation per default to
localhost::3000 . Beforehand,
webpack bundles your dependencies and watches your files and its configuration so that it automatically reloads if there are any changes. Consequently, you’ve got the full peace of mind. Just start coding and see the changes instantly appear on the screen!
There also is an npm script for building, namely
npm build . It lints your code, runs webpack in development mode and executes the tests. This is untested so far and should be considered a placeholder for how a build script could look like. A real build script should optimize and minify files et cetera.
2. Utilized Tools
- Docsify: Automatic Documentation Generator
- Arduino Create Agent JS Client JS implementation of Arduino Create Agent to interact with our boards via serial port.
- Webpack: Dependency Bundler
- Babel/Babel Loader: JS transpiler for unified language version and browser support
- ReactJS: Front end library
- mobx: Data-flow and state management for react components library
- RMWC: UI library wrapping Material Components in React components
3. Overall Design Considerations
Docsify was used for its beautiful and effortlessly to write documentation. It suffices for generating a nice web documentation for our project, however we wanted to have interactive elements using data from the board.
Arduino Create Agent is very feature rich and was therefore prefered over Chilipeppr, which is better documented but cannot flash software on the board for example. Arduino Create Agent has few documentation, but is well maintained and mature as it is used for the Arduino Web IDE. It can flash software on the board and even load drivers, which are very sophisticated features. Both Chilipeppr and Arduino Create Agent are based on the Serial Port JSON Server, which needs to run locally on the users machine.
To use the common package manager npm but still run the scripts on the client side, Webpack bundles the dependencies in a single file, injected in the index.html . It also bundles the source code and transpiles it to ES2015 using Babel and Babel Loader for interoperability with dependencies and to work on older browsers.
Concerning the dynamic frontend code, ReactJS is the go-to library for rendering UI elements in a structured way. AngularJS is an equally powerful and popular alternative and was disregarded only because of personal preference. For the same reasons Material Components Web was selected as CSS framework. The official React implementation is in fact less mature than RMWC (as of now) and was therefore disfavored.
mobx is a Flux inspired data flow architecture to manage states of React components. Compared to Flux and implementations like AltJS, mobx removes a lot of boilerplate code and yet remains unopinionated on the way the data changes occurs (essentially removing actions ). This especially leads to out-of-the-box support for async and external data alterations and is a huge advantage over otherwise popular Redux, because the daeomon of Arduino Create Agent JS Client updates the data unregularly when there state of the serial connection changes (new message via serial port, new board connected, …).
4. Documentation of NPM Scripts
Runs webpack in development mode and watches the files for changes, to automatically rebuild on changes. Additionally nodeman watches for changes of the webpack config file and restarts webpack.
Runs webpack in production mode.
Makes docsify serve the documentation in docs/ . Default serving location is localhost::3000 .
Executes ESLint checks on all *.js files in docs/ .
Empty so far, can be used for (unit) tests
Runs webpack:dev and docsify in parallel using npm-run-all . This bundles the files and reloads them on changes, while serving the docs via docsify.
5. Folder Structure
6. Data Flow
Deployment has yet to be setup properly. So far the contents of the docs folder are manually copied to the howto.makeradar.com directory on the webspace. Since this is a git repository, webhooks could be setup to trigger a git pull on the webserver.
8. Known Issues
1. Multiple iframes in one page
So far, including two iframes in one page breaks it. The workaround is to include the iframes with HTML code. See here for the respective issue.
2. Redundant code in iframes
Currently, every iframe has its own DaemonActions.js , SerialConsoleStore.js and SerialConsoleStore.js . This is very redundant and especially bad for maintainability as the implementations even vary slightly from iframe to iframe, making it very hard to stay on top of that.
rawDataConsole was the first iframe (basically prints serial messages). From it, showRAWData (adds message processing) evolved and doorOpener , showFFT and showSpeed (add FFT and speed calculation) should have the same code, only different views.
Actually, the software was designed with modularity in mind. It is capable of having one backend and just varying views for the iframes. Only the showSpeed backend code would be needed for example. For the different iframes, there could just be different view components (e.g. fftSpectrum , IQplot , Tachometer , …).
The other option would be to reduce each iframe strictly to the functionality it needs (and not have a complete implementation in every iframe as it is now). However, as at least three iframes need the FFT, there’d be still a lot of redundancy left.
Why not have just one backend then?
It is simply and unfortunately not technically possible, due to the constraints of docsify and React. One could run only on JS on the whole page and have the different views displayed in different locations on the page. But docsify just executes one script tag per page and React does not allow components to be rendered in different locations on a page. The problem is that the text sections of the .md file need to be parsed by docsify and the JS components inbetween should come from React. There is no solution, we are aware of, to do this, so far. Also performance-wise the redundant processing is an issue.
Maybe a solution could be the window messaging API. But this would require some effort and its questionable if it’s fast enough