Mission Manager (AFC-MW)

1. What is the Mission Manager?
2. How to generate the Mission Manager bundle
3. How to configure the Mission Manager
   1. Configuration before running the Mission Manager
   2. Configuration during the execution of the Mission Manager
4. How to run the Mission Manager
   1. How to run the Mission Manager as a standalone application
   2. How to run the Mission Manager as a Docker container
5. Monitoring the Mission Manager
   1. Logs
   2. Mission related files
6. License

What is the Mission Manager?

As described in Deliverable 2.3 - Architecture Requirements and Definition, the mission manager is:

[...] the component manages all operations and data flows in which vehicles (i.e., GVs, UAVs) are involved. The main duties of this component are related to the delivery of the mission plan defined by the Farm Management System, as well as receiving the information from the vehicles that participate in the mission according to its progress.

Also, this component is responsible for sending events to elements in the Hardware Layer. We will consider as events all relevant data (e.g., command to abort a mission) sent by the middleware that should be considered by vehicles or other IoT devices. Events will be generated by the Farm Management System as a result of an analysis of data

In particular, this component is able to:

• Receive a request for the initial status of the vehicles (System Configurator) through a dedicated REST interface.
• Receive a full mission from the MMT through a thrift interface.
• Parse the received mission and:
  • Generate the vehicle plan for each autonomous vehicle participating in the mission, and publishing it to the MQTT broker.
  • Generate the JSON representation of the prescription map for one tractor participating in the mission, and sending it to the ISOBUS Converter.
• Receive the abort events for both vehicles and mission, and publishing it to the MQTT broker.

How to generate the Mission Manager bundle

Use mvn install from the Mission Manager project folder (the one with the pom.xml file). This will generate a file named MissionManager-1.0-SNAPSHOT-jar-with-dependencies.jar inside the target folder.

How to configure the Mission Manager

At this stage the Mission Manager have some properties that define its behavior, and that can be configured. These properties are:

• thrift.port defines the port for the thrift service provided.
• thrift.style defines the type of thrift service style used. By default it use multiplex.
• rest.port defines the port for the REST services provided. This includes the REST service for the System Configurator, as well as some other REST services for monitoring and configuring the Mission Manager while it is running.
• rest.base_uri defines the base uri for the REST services provided.
• mmt.ip defines the address of the MMT.
• mmt.port defines the port of the MMT thrift service.
• mmt.enabled_notifications defines if the Mission Manager is enabled or disabled to send notifications to the MMT.
• mqtt.protocol defines the protocol used by the MQTT broker. By default it is set to ssl.
• mqtt.server defines the server address for the MQTT broker.
• mqtt.port defines the port for the MQTT broker.
• mqtt.user defines the username for accessing to the MQTT broker.
• mqtt.pass defines the password for accessing to the MQTT broker.
• mqtt.client_id defines the client id for accessing to the MQTT broker. By default is set to AFC Mission Manager.
• mqtt.topic.mission defines the schema for the topic levels related to a mission.
• mqtt.topic.system_configuration defines the schema for the topic levels related to the system configuration.
• mqtt.retained.missiondefines the retained property for the MQTT related to missions.
• mqtt.retained.system_configuration defines the retained property for the MQTT related to system configuration.
• sc.request.timeout defines the timeout for the status vector request from the System Configuration.
• sc.max_vehicles defines the maximum number of vehicles that can reply to a status vector request from the System Configuration. Only for test purposes.
• dq.server defines the server address for the Data Query component.
• dq.port defines the port for the Data Query component.
• isobusconverter.server defines the server address for the ISOBUS Converter component.
• isobusconverter.port defines the port for the ISOBUS Converter component.
• last_sequence_number defines the las used sequence number for messages published to the MQTT.
• debug defines the logging of debug information.

Configuration before running the Mission Manager

To configure the Mission Manager before running the Mission Manager, create a file named local.properties in the same folder where the .jar is, and add the configuration properties you need.

Configuration during the execution of the Mission Manager

To check the current configuration being used by the Mission Manager, go to http://server_address:rest.port/rest.base_uri/MissionManager/conf, where:

• server is the address where the Mission Manager is running.
• rest.port is the port the Mission Manager is using for REST services, set by the property with the same name.
• rest.base_uri is the base URI for the REST services run by the Mission Manager, set by the property with the same name.

To change any configuration property, make a PUT request to the same address as before (http://server_address:rest.port/rest.base_uri/MissionManager/conf), with those properties that need to be changed sent as application/x-url-form-encoded with their new value.

NOTE: Every change made during the execution of the Mission Manager is made permanent, and stored in a configuration file called stored.properties. This file can be modified and/or removed if required. The priority of the configurations is as follows: if a property has a stored value in stored.properties, that value is used. If a property does not have a stored value, but it is defined as in local.properties, then that value is used. If a property does not have neither a stored value, nor a local value, then the default value is used.

NOTE: There are some properties that cannot be changed while running the Mission Manager:

• rest.port
• rest.base_uri

How to run the Mission Manager

The Mission Manager is implemented to be run as a standalone application inside a Docker container. Therefore, for testing purposes it can also be run as a standalone application without Docker.

How to run the Mission Manager as a standalone application

The Mission Manager requires Java JRE 8 or higher. To run the Mission Manager, execute java -jar MissionManager-1.0-SNAPSHOT-jar-with-dependencies.jar.

A valid mqttTrustStore.jks file is required in the same folder as the Mission Manager in order to access to the MQTT Broker.

How to run the Mission Manager as a Docker container

To create a docker image, it is recommended to use the openjdk:12-jdk-alpine as the base image, as it is enough of running the Mission Manager, and has a small size compared to the openjdk image using Debian.

The use of openjdk:12-jdk-alpine also provides with two interesting advantages over 8 to 11 JDK Alpine versions:

• It allows to enable a memory and CPU restriction for the execution of the container. This is available from version 9. Version 8 officially supports it, but it can be buggy.
• It includes the Java Mission Control that allows to monitor and record the performance of the Mission Manager using the Java Flight Recorder tool (only available directly from version 12).

The example Dockerfile used for running the AFC Mission Manager for the different scenarios is as follows, using a different local local.properties file for each scenario:

# Base Alpine Linux based image with OpenJDK JRE only
FROM openjdk:12-jdk-alpine
# Install bash
RUN apk add --no-cache bash
# copy application JAR
COPY MissionManager-1.0-SNAPSHOT-jar-with-dependencies.jar /usr/app/MissionManager.jar
COPY mqttTrustStore.jks /usr/app/mqttTrustStore.jks
COPY local.properties /usr/app/local.properties
WORKDIR /usr/app
# specify default command
CMD ["java", "-jar", "MissionManager.jar"]

Save the previous Dockerfile example and modify it according to each specific case.

To build the Docker image, execute docker build -f Dockerfile -t mman:latest

Once the Docker image is created, it can be run executing docker run -d --name mman-test -p extThriftPort:portThrift -p extRESTPort:portREST -m 512m, where portThrift and portRest are the ports for the Thrift and REST services used by the Mission Manager within the container, and extThriftPort and extRESTPort are their corresponding published ports in the host machine.

Please, be aware that by default the timezone applied to an Alpine based image uses UTC by default. Change it to your needs accordingly.

Monitoring the Mission Manager

Logs

The logs for the Mission Manager can be accessed via REST through http://server_address:rest.port/rest.base_uri/MissionManager/logs/MissionManager.log.

Mission related files

The mission received from the MMT, as well as the generated files from it can be accessed through http://server_address:rest.port/rest.base_uri/MissionManager/missions. The missions are stored in separate folders per day (for v1.0.0-rc5). For each mission, there should be the following files:

• AFC-Mission-date-hour-missionID-requestId.ser: This is the mission file as received from the MMT, stored as a serialized object.
• AFC-Mission-date-hour-missionID-requestId.json: This is the mission file received from the MMT represented in JSON format. NOTE: NaN values are changed to Double.MAX_VALUE, as JSON has no representation to NaN.
• AFC-CSV-date-hour-requestId-missionId-commands.csv: Parsed commands from the received mission.
• AFC-CSV-date-hour-requestId-missionId-forbidenArea.csv: Parsed forbiddenArea from the received mission.
• AFC-CSV-date-hour-requestId-missionId-homeLocation.csv: Parsed homeLocation from the received mission.
• AFC-CSV-date-hour-requestId-missionId-navigationArea.csv: Parsed navigationArea from the received mission.
• AFC-CSV-date-hour-requestId-missionId-tasks.csv: Parsed tasks from the received mission.
• AFC-CSV-date-hour-requestId-missionId-vehicles.csv: Parsed vehicles from the received mission.
• AFC-VP-date-hour-requestId-missionId-vehicleId.json: Parsed vehicle plan for vehicleId from the received mission. This is the same content published to the MQTT Broker.
• AFC-PM-date-hour-requestId-missionId-vehicleId.json: Parsed prescription map for vehicleId from the received mission. This is the same content sent to the ISOBUS Converter.
• AFC-PM-date-hour.xml: Generated prescription map received from the ISOBUS Converter.

License

The Mission Manager for AFC is distributed under a dual license scheme:

• For academic uses: Licensed under GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
• For any other use: Licensed under the Apache License, Version 2.0.

For further details on the license, please refer to the License file.