Zum Inhalt

lennix-diag-back

The backend that runs on the controller and communicates directly with lennix. It is the only way of interacting with lennix from outside providing the following options:
- startup
- shutdown
- set and get config
- get live data (websocket)

Services based on these actions will be available via an external frontend project, lennix-diag-front.

Commissioning

  1. clone repo into /home/lehnert/lennix-pro-dist/lennix-diag-back
  2. cd /home/lehnert/lennix-pro-dist/lennix-diag-back
  3. npm install
  4. link to, or copy lennix-diag-back/service/lennix-diag.service into /etc/systemd/system/
  5. systemctl daemon-reload
  6. systemctl enable lennix-diag.service
  7. deploy lennix-diag-front (It is important that it is in place before starting!)
  8. systemctl start lennix-diag.service
  9. done

If there is trouble reaching the backend check the ip and port in config/production.json.
Same goes for paths. Though, if everything is checked our like the following then it should work.

lennix-pro-dist/
lennix/
lennix-diag-back/
lennix-diag-front/
dist/

Dependencies

The summary of the dependencies, details can be seen in Overview.

For a complete list including all subdepencies of feathers see package.json dependencies.

Tools

Overview

The backend is based on node.js which is a javascript framework for backend development that comes with a lot of tools itself and also offers a valuable environment of handling the project and its dependencies via the node package manager.

Tasks

The function requirements of this software are:

  • Handling the state of the lennix process, it must be possible to startup, shutdown and reset the lennix process and its configuration if necessary. This also includes starting the calibration process the lennix tool offers
  • The way lennix works is strongly dependent on its parameter set. This software must be capable of receiving this parameter set and forward it to a frontend application. It must also be possible to forward changed parameters back to lennix.
  • Additional to the parameter configuration, lennix sends live values, like the cranes position, dynamic obstacle data and so on. These values must be forwarded in a fast manner, such that a frontend application can render them real time e.g. in a dynamic diagram.

Communication

There are two important communication channels.
1. lennix <-> lennix-diag-back
2. lennix-diag-back <-> lennix-diag-front

lennix <-> lennix-diag-back

The communication between the backend and lennix is handled via udp socket (sender/receiver). Both processes are on the same machine (localhost).

lennix-diag-back <-> lennix-diag-front

The communication between lennix-diag-back and lennix-diag-front is handled with two mechanics.

First, a REST API based on Express that handles requirements like getting or setting config parameters and manage the lennix process.

Second, the live data provided by lennix must be accessible in real-time. Therefore, websocket technology is used provided by SocketIO. This communication channel goes in only one direction, back to front.

Project Organization

As said the node package manager npm is used for project organization. All important informations and the dependencies of the project are stored in the package.json.

This has the advantage that after a pull to a new machine only npm install has to called and all dependencies are managed automatically.

The preferred IDE is going to be Visual Studio Code that comes with all the tools needed, e.g. an npm capable terminal even for windows, debugging tools and linting tools. It is capable of code highlighting and auto completion for all needed languages including the frontend project (Javascript, Typescript, HTML, CSS).

The overall project directory structure is determined by Feathers. Not only is it recommended by the Feathers framework, it is also a common organization for backend projects and employs best practices.

Code Style

Of course, it is always important to follow a consistent code style. For this project it is going to be based on AirBnB which is ES6 compatible. In combination with the linting tool ESlint these rules are enforced. However, there are some rules in the AirBnB standard that must be altered for our project, some globally others on the demand.

The following rules are going to deviate from AirBnB:

  • no-plusplus : off: since increment and decrement statements like i++ are very common and widely used especially in loops. The argumentation that they can cause silent errors and i = i + 1 is more expressive is not significant enough to obey that rule.
  • comma-dangle: off: The only advantage of this rule would be that only one line must be edited when later adding a new field. Though, it proofed annoying in practice since we are all used to omit the comma after the last field.

A common local exception is the no-unused-vars rule. This is sometimes necessary due to the used frameworks. On the other side it must not be active globally since real unnecessary vars should be avoided.

Test scripts may also have local differences due to the nature of the used test frameworks.

It is also noteworthy, that 'use-strict' is not necessary with the used linting setup, since it enforces these rules anyway.

REST and Websocket

The framework of our choice is Feathers. It comes with both REST functionality as well with Websocket support which is important for real-time applications like displaying live diagramms of the crane state.

The REST functionality Feathers delivers is based on Express which is the most popular framework and thus very robust. The websocket functionality on the other hand is based on SocketIO which is also very popular and widely used. Feathers wraps these frameworks and more into a lightweight library that offers both performance and stability.

Frontend

AngularJSis used. Both Feathers and Angular are compatible. See the lennix-diag-front project for further details.

Documentation

JSDoc is used.

Tools

Postman is a powerful tool to test the RESTful API in terms of QA.

Testing

The basic unit test framework we use is mocha. Mocha has the advantage that it handles async methods without problems. Chai is the assertion library that supports the unit test implementation.

Using the Feahters generate command, tests are also generated which can be a good basis to test services and hooks.

Logging

The general logging of lennix-diag-back is done via the winston logger that comes with a fixed set of log levels.

  • Error: Error path/filename, reason for error
  • Warn: Warn path/filename, reason for warning
  • Info: info
  • Verbose: info

Profiling

For profiling two different tools are used in combination. The profiler that comes with node itself and Apache Bench to stress test the REST API.

TODOS

  • Handle error when no lennix instance can be found or started, answer with an according error message in this case in process-service (dependend on new system-d approach)