Developer Notes

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:

  1. Quick Start: Local setup, running and building
  2. Utilized Tools: List containing all used tools
  3. Overall Design Considerations NPM script documentation
  4. Folder Structure
  5. Data Flow
  6. Deployment
  7. Known Issues

1. Development Environment Setup


We’ll be assuming you have the following software already installed on your computer




To develop with this repository, you need to clone it first.

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

  1. Docsify: Automatic Documentation Generator
  2. Arduino Create Agent JS Client JS implementation of Arduino Create Agent to interact with our boards via serial port.
  3. Webpack: Dependency Bundler
  4. Babel/Babel Loader: JS transpiler for unified language version and browser support
  5. ReactJS: Front end library
  6. mobx: Data-flow and state management for react components library
  7. 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

     1. webpack:dev

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.

     2. webpack:prod

Runs webpack in production mode.

     3. docsify

Makes docsify serve the documentation in   docs/  . Default serving location is   localhost::3000  .

     4. lint

Executes ESLint checks on all   *.js  files in  docs/  .

     5. test

Empty so far, can be used for (unit) tests

     6. start

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

7. Deployment

Deployment has yet to be setup properly. So far the contents of the  docs   folder are manually copied to the   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