Quick Intro

What is MEP?

MEP is a modular and extendable development platform for programming autonomous robots (Eurobot). It provides an abstraction on top of many hardware components (drivers) to be used in a simple API for defining robot's behaviour (strategy). Also, it has built-in sensor fusion for obstacle detection and precise localisation, obstacle bypassing, task scheduling, communication (services), simulation support, as well as basic features like logging and configuration.

Memristor team is working hard in order to implement computer vision and enhance current algorithms. Programming style and patterns are the result of many years of experience competing on Eurobot competition.

MEP master is the central component in MEP and it has a role of the brain in the system. It designed to run on Linux based embedded development boards (like Raspberry Pi).

Big picture simple	Big picture full

Getting Started

For easy understanding, in further text, Raspberry Pi will be used as a development board.

Linux installation

Please follow official Raspbian installation instructions https://www.raspberrypi.org/documentation/installation/installing-images/README.md

Please use one of those Linux images:

• official Linux distribution for Raspberry Pi or
• Memristor's Raspbian edition

SSH connection

To connect to Raspberry Pi from your computer and type commands remotely SSH is required. To configure SSH please follow next tutorial: https://www.raspberrypi.org/documentation/remote-access/ssh/

mep-master installation

Please make sure your SSH connection is ready because all following commands will be used in SSH! To install MEP master use the following command: curl https://raw.githubusercontent.com/Memristor-Robotics/mep-master/master/install | sh The command will download MEP master source files and install all dependencies.

Hello World move

Before your robot make the first step please check if everything is connected properly (eg. batteries and electronic boards), put your robot in the middle of a terrain and run: ./mep -c strategies/boilerplate/DefaultScheduler.js This command will execute a strategy located in strategies/boilerplate and your robot should go 10cm forward and backwards. If the robot went forward and backwards then congratulations! That means software, electronics and basic mechanisms works fine. Now, the rest should be easy.

Check ./mep -h for more parameters.

Strategy

The strategy defines robot's behaviour, what robot should do and how to react to opponent strategy or hardware failure. Each strategy consist of many tasks and each task consists of multiple commands. A brain of each strategy is scheduler which should have advanced logic (eg. AI) and it orders task priority by the environment.

Strategies are designed to be easily editable by students who don't have a background in programming!

Setting up new strategy

In strategy directory is located boilerplate strategy. The boilerplate strategy is very simple and well-documented strategy intended to be base code for your new strategy.

Please follow this tutorial to set up new strategy.

List of commands

In file src/strategy/Shortcut.js is a list of shortcuts you can easily use in your strategy. Also, you can extend the list of shortcuts for each strategy by putting in a common file like it is done in boilerplate example.

Note that all commands are asynchronous and you need keyword await in front of command if you want to wait it is fully executed.

• go(x, y[, params]) Go to location (x, y) using additional params.
  • alias services.motion.MotionService.go()
  • example await go(0, 0) Go to the center of a terrain.
  • example await go(0, 0, { backward: true }) Go to the center of a terrain, but go backwards.
• rotate(angle[, params]) Rotate robot for given angle.
  • alias services.motion.MotionService.rotate()
  • example await rotate(50) Rotate robot for 50 degrees in the current position.
• straight(distance) Move robot straight for given distance in mm.
  • alias services.motion.MotionService.straight()
  • example await straight(50) Move robot 50mm forward.
• home() Return robot to it's home position.
• delay(mills) Do nothing for mills milliseconds.
  • alias misc.delay()
• driver(driverName) Get driver instance by it's name.
  • alias drivers.DriverManager.getDriver()

Configuration

All configuration files are located in config directory. Configuration is used to:

• configure services (eg. static obstacles, default parameters for movement...),
• initialize and configure drivers (eg. communication protocols, analogue and digital pins, motion driver...) &
• general purpose parameters (eg. logging, table name, match duration...).

Default configuration is located in config/default.yaml and it is overriden by config/[robot_name].yaml. And if simulation is turned on than config/default.yaml and config/[robot_name].yaml are overriden by config/[robot_name].simulation.yaml. Therefore, config files are inherited as config/default.yaml > config/[robot_name].yaml > config/[robot_name].simulation.yaml.

Just like strategies, the configuration is designed to be easily editable by students who don't have a background in programming!

Initializing PinDriver

PinDriver is just an example and in a similar way you can initialize and configure any other driver. List of available drivers is available in directory src/drivers.

Here is an example how to add driver configuration (eg. config/big.yaml):

Drivers:
  CollectorBigTrack:
    "@class": drivers/pin/PinDriver
    "@load": true
    "@dependencies":
      communicator: CanDriver
    cid: 0x00007F06
    direction: 'output'
    mode: 'digital'

and how to use initialized driver in strategies:

driver('CollectorBigTrack').write(100)

CollectorBigTrack is unique name of driver that is used in strategies to acccess to the instance of the driver, as well as to tag purpose of driver (to be more readable). @class, @load and @dependecies is minimal set of parameters for each driver and it has following meaning:

• @class JavaScript class that defines behaviour of driver (eg. drivers/pin/PinDriver).
• @load Determines if driver should initialized and can be true or false. It is useful when you want to quickly disable driver or disable driver by overriding that parameter.
• @dependencies List dependecies that drivers has. If driver has dependencies than dependencies will be loaded first and if one of dependecies fails you will be notified why your driver doesn't work. Other parameters are driver specific:
• cid Communication ID (or CAN ID).
• direction Pin can be output or input.
• mode Mode can be digital or analog.

You can find all driver specific parameters in a source code (if does't exist in API reference) in constructor of driver (eg. drivers/pin/PinDriver, look for Object.assign).

Drivers

Provides an abstraction on top of many hardware components.

Hello World Driver

HelloWorldDriver meets minimal requirements to become a driver. All drivers are located drivers

class HelloWorldDriver {
  constructor(name, config) {
    Mep.Log.debug('Hello World');
  }

  provides() { return []; }
}

Each driver gets variables name and config in constructor. name is unique name of each driver instance, and config is configuration object for instance of the driver.

Method provides() can return an empty array or array of strings which represents data that can be provided by a driver. If the driver provides some type of data it must meet requirements for that type of data. More will be explained.

All drivers are located in directory /drivers and by convention have dedicated directory, eg. SkeletonDriver is stored in /drivers/skeleton/HelloWorldDriver.js.

Every driver must be added in a configuration file. By adding our driver in configuration file, DriverManager knows that our driver should be instantiated.

Drivers:
  ...
  HelloWorldDriver:
    '@class': 'drivers/skeleton/HelloWorldDriver',
    '@init': true

An example of a driver in configuration file.

Source Roadmap

• docs Documentation and guidelines
• logs File logs
• config Configuration files
• src Source code of the core, services and drivers
  • drivers Hardware abstraction layer, drivers and driver management core
  • services Abstraction layer on to of drivers, algorithms, logic etc.
  • strategy Custom data types, classes, important for strategy
  • misc General purpose libraries, functions and classes
• strategies Source code for strategies (to be replaced in separated repo)
• test Unit tests

Logger

Please don't use console.log(message)! Instead of that use built in logging system Mep.Log.debug(module, message). For more details please check reference for Log class.

Logger configuration

Configuration can be done via configuration file located under src/config directory.

Sample configuration:

"Log": {
  "console" :{
    "active" : true,
    "outputMode" : "short",
    "color": true
  },
  "file" :{
    "active" : false,
    "file" : "javascript.log",
    "period" : "1d",
    "count" : 3
  },
  "elasticsearch": {
    "active" : false,
    "level" : "debug",
    "host" : "http://localhost:9200",
    "indexPattern" : "[mep2_logs-]YYYY-MM-DD",
    "type": "log"
  }
},

Loggers

console

Console logger parameters:

• active (false): true/false : activate console logger
• outputMode (short): short|long|simple|json|bunyan see bunyan-format
• color (true): toggles colors in output

By default log level is debug.

file

File logger parameters:

• active (false): true/false : activate file logger
• file (javascript.log): log filename, either an absolute path, or relative to ./logs directory
• period (1d): rotate log every day
• count (3): backup only

By default log level is debug.

elasticsearch

• active (false): true/false : activate elasticsearch logger
• level (debug): debug/info : debug level
• host (http://localhost:9200) : elasticsearch server http address
• index (mep2_logs) : elasticsearch index name. (no pattern allowed here)
• indexPattern ([mep2_logs-]YYYY-MM-DD) : elasticsearch index pattern. Can be a static name or a dynamic with YYYY-MM-DD pattern.
• type (log): elasticsearch type

If index is configured, indexPattern is ignored.

Performance Parameter

Log are impacted by "performance" parameter, if "performance" == true : Log level is limited to "info" for all loggers.

Goals

Modular

Every driver or service can be easily replaced and tested separately.

Team orientated

There is big picture & every module is separated.

Easy & fast to make a change

Because it is JIT you don't have compile and transfer over the network

Fast learning curve

Software should be well organized and documented.

Tested

Every module should be tested using Unit tests.

Package manager

Don't rewrite software, if there is already packet written use it.

Hardware independent

Services should be independent of drivers, practically that means if we disable LidarDriver TerrainService should work just fine.

Logging system

Elastic Search & Kibana will help us to find a bugs.

Telemetry

As a space shuttle all is automatic during launch, Robot should have a mean to get all telemetry out of the box and send them to space nearby for team to analyze, understand and act to adapt or correct parameters for the next launch.

A Telemetry system is composed by :

• a set of robot modules with real time KPI (Key Point Indicators)
• a mean to transmit efficiently information to base
• a base telemetry reception to record all information
• a set of dashboards to view and analyze data

KPI Probes

Each Robot modules has his own set of KPI based on module functionality.

For example, a battery device has following KPI :

• Charge
• Temperature
• Battery high and low voltage threshold
• Real time Amperage consumption

Each of this measures can be collected via Probes and transmitted to base.

Efficient Transmission System

Transmission between Probe and outer world should have a limited effect on Robot System and capabilities. Like a droid in the dark, standing alone, it must transmit data at a fix rate but does not requires any external action to work. Like UDP transmission : sending bottles in the sea without acknowledging any response.

Transmission should also be efficient in sent information, this means data format has to be tuned to avoid unnecessary data structure decorator to minimize telemetry packet size.

Needs between telemetry information, packet optimization, data transmission should be optimal vs System computation and resources consumption.

Base Data Recorder

Data Recorder receive data from anywhere and log them into data storage. Data recorder must be :

• Simple and reliable
• Able to receive Telemetry from multiple robots at the same time (origin must be logged)
• Store received information even if data are corrupted or partial
• Provide a way to extract recorded information either in real time or request based

Telemetry Dashboards

Recording data is a key function, but without any dashboard to let Human understand what's going on it's useless. Dashboard should be able to :

• Provide raw data access
• Provide visual information easy to understand

Implementation

KPI Probes

Probes should transmit a metric packet with :

• Origin
• Metric date
• A set of
  • Metric type
  • Metric value