HTTP Interface

The HTTP REST API provides access to almost any functionality of the PlatformPilot via the HTTP protocol.

The HTTP server is enabled by default on port 8888, however it can be disabled by setting enable_http_server to false.

The REST API is available on the path http://localhost:8888/api/. (replace localhost with your target machine)

See also HttpProxy.

Login

Some functionality requires special permissions, see User Management.

To gain necessary permissions you need to login to the HTTP server as follows:

curl -I "http://localhost:8888/server/login?user=neo-user&passwd_plain=neobotix"
HTTP/1.1 200 OK
...
Set-Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8; Path=/; Max-Age=86400; SameSite=Strict;

The response will contain a session cookie which can be used as follows:

curl -H "Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8" http://localhost:8888/api/request/...

Services

All modules of the PlatformPilot are available via the path /api/request/.

To get an overview of the available modules:

curl http://localhost:8888/api/request/
["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "HybridPlanner/", ...]

The available methods of a module can be queried as follows:

curl http://localhost:8888/api/request/HybridPlanner/
["append_goal", "append_goal_position", "append_goal_positions", "append_goal_station", ...]

A method can be called as follows:

curl -X POST http://localhost:8888/api/request/PilotServer/get_state
{"__type": "pilot.PilotState", ...}

curl -H "Cookie: ..." -X POST -d '{"name": "Station1"}' \
        http://localhost:8888/api/request/HybridPlanner/set_goal_station

The parameters of a function are supplied as a JSON object via POST data.

You may need to be logged in to access certain functions, see above.

Topics

Almost all topics of the PlatformPilot are available via the path /api/topic/.

To get an overview of the available topics:

curl http://localhost:8888/api/topic/
["input/", "local_planner/", "navigation/", "platform/", "sensors/", "task_handler/", "tf/", "tfd/", "vnx/"]

curl http://localhost:8888/api/topic/platform/
["info", "odometry", "pilot_state", "system_state"]

To get the latest sample data of a topic:

curl http://localhost:8888/api/topic/platform/odometry
{"__type": "pilot.Odometry", "time": 1613656049067588, ...}

To get a tree of the lastest sample data of a domain:

curl http://localhost:8888/api/topic/platform
{"info": {"__type": "pilot.PlatformInfo", ...}, ...}

To publish a data sample on a topic:

curl -H "Cookie: ..." -X POST -d '{"topic": "test.topic", "sample": {"__type": "pilot.Pose2D", ...}}' \
        http://localhost:8888/api/request/HttpProxy/publish

Note that a __type field needs to be specified containing the type name of the sample, such as pilot.Pose2D for example.

Configuration

The current configuration tree can be viewed via the path /api/config/.

To access protected configuration values, a special permission PROTECTED_CONFIG is required, see vnx.permission_e.

To get an overview of the available config options:

curl http://localhost:8888/api/config/
["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "GridMapping/", ...]

curl http://localhost:8888/api/config/GridLocalization/
["broadcast_tf", "confidence_gain", "constrain_threshold", "constrain_threshold_yaw", "gain_factor", ...]

To query a specific config value:

curl http://localhost:8888/api/config/GridLocalization/gain_factor
0.01

To query a sub-tree of the configuration:

curl http://localhost:8888/api/config/GridLocalization
{"broadcast_tf": true, "confidence_gain": 0.01, "constrain_threshold": 0.1, "constrain_threshold_yaw": 0.2, "gain_factor": 0.01, ...}

To query the entire configuration tree:

curl http://localhost:8888/api/config
{...}

Log

The terminal output log messages are available via the path /api/log/.

Each message is of type vnx.LogMsg.

To get all errors which occured since startup:

curl http://localhost:8888/api/log/errors
[...]

To get all recent messages:

curl http://localhost:8888/api/log/recent
{"1": [...], "2": [...], "3": [...], "4": [...]}

To get recent warnings only:

curl http://localhost:8888/api/log/recent/2
[...]

The log levels are as follows:

  • 1 = ERROR
  • 2 = WARN
  • 3 = INFO
  • 4 = DEBUG

Log messages are also written to disk and can be accessed via http://example:8888/user/data/logs/.

Events

A history of events is available via the path /api/events/.

Each entry is of type pilot.Event or any of it’s derived types such as pilot.Incident.

To get a list of recent events:

curl http://localhost:8888/api/events/recent
[...]

To get recent error events only:

curl http://localhost:8888/api/events/errors
[...]

The latest events are at the end of the respective list.

Views

For certain data types there are special views available via the path /api/view/.

To get a cost map (see pilot.CostMapData) as a PGN image:

curl "http://localhost:8888/api/view/cost_map?topic=navigation.local_cost_map&color=true&alpha=128" > local_cost_map.png

To get a grid map (see pilot.OccupancyMapData) as a PGN image:

curl "http://localhost:8888/api/view/occupancy_map?topic=navigation.grid_map&alpha=255" > grid_map.png