Remote Mapping API

Sven Köhler
Maparchitecture.jpg (123251 bytes)
Mapplatforms.jpg (232778 bytes)

Remote Mapping API

General Overview

  • This architecture proposes separate classes for 1. sending map data 2. receiving control data 3. map display 4. GUI input. Commands are not tied to a GUI in any way because it should be possible to receive commands by a command line, clicking, or whatever input device the user wants to use to control aspects of the robot. He simply uses CommandServer methods to send one of the predefined commands.
  • The proposed API is used to program custom GUI apps by the user. A small sample will be included in the samples directory.
  • The architecture proposes a full featured Map Application that resides in the bin directory (also runnable from the leJOS Eclipse plugin). This GUI is designed to allow the most common display and control commands.
  • The server is on the PC side (not on the NXT) because at some point we will probably want to allow multiple NXT bricks to display their data to a single Map GUI on a PC.
  • One reason to separate the command API from the map display API is that the GUI can be used to ''display'' two or more NXT robots, but the default MapApp would not be used to ''control'' two robots. So if someone is programming a GUI to display many robots, they would probably not bother adding a control GUI for each robot.
  • The architecture works with all NXJ platforms: NXT app directly using Mapper, NXT app-PC App, PC Comms, Android:

The Classes

NXT Application

The user creates their own NXT application. To use this API, they would likely use Navigator and/or Pilot classes. The NXT application can run on either the NXT brick (most common) or on the PC (either as a PC Comms project, or a PC app with another app running on the NXT). Their code would also contain a Mapper class to interact with the mapping API.


The Mapper is similar to the DataLogger in that it is a class that is accessible by the user and can send data to the PC via Bluetooth for display. The Mapper sends the following data: Move, Pose, Waypoint, etc.. Most data would probably be updated at the end of a move, but it could also poll a MoveProvider for real-time updates to the move while it is happening.

  • lines
  • line maps
  • grid squares
  • grid maps (we lack this in our API currently)
  • waypoints
  • particle set
  • nodes (for node searches)
  • moves (for replaying paths traveled by a robot)
  • range readings


The MapServer accepts data from an InputStream (in most cases Bluetooth) and sends data with an OutputStream. However, it could receive streams set up by a multitude of robots that are communicating from other PCs on the network using the standard classes. If a Mapper is run on the local PC, it would probably use and localhost to connect to the MapServer class. The MapServer would probably need to run one thread to accept Bluetooth communications and another thread to accept incoming communications. The MapServer is not its own separately executing application, it is a class instantiated by the Map Application on the PC side.

In cases where some code is running on the NXT brick (Navigator for example) and some code is running on the PC (the Map data, Pathfinder, etc...) the NXT is sending map data updates via Bluetooth, while the PC side is sending data to the MapServer via localhost.

Other MapServer Functions

  • The information comes in as a stream. Therefore it would be easy to stream it into a File to save the full data run for later display and playback.


The CommandServer has methods for controlling aspects of the navigation package. CommandServer would probably only accept one connection per NXT at a time (it would probably not allow two connections to control the same robot). The protocol for this server makes sure commands are sent to a specific NXT robot. In other words, methods in CommandServer must specify the NXT robot name or some other identifying id so as not to confuse which robot the commands are meant for. I'm unsure if the CommandServer could be used to request data (such as the WayPoint queue from the Navigator)--we'll need to try an application and see if it is necessary.

Like the MapServer, it has a thread for Bluetooth connections and one for If a command is sent it is eventually received by the robot code (NXT and/or PC COmms) via the CommandListener. The users Listener code can choose to use or ignore data. For example, if MCL is running on the PC side and the Navigator is running on the NXT, MCL Commands would be ignored by the NXT listener code. If a command is sent to move to a new waypoint, the PC side user code would ignore it.

Possible commands

  • A waypoint
  • A series of waypoints
  • Command to clear waypoint queue
  • Command to request waypoint queue? (results in it sending data to MapServer?)
  • Command to set the Pose of a PoseProvider?
  • The range of pilot moves (travel, arc, rotate, stop)


The Commander accepts a single InputStream from Bluetooth. The Commander waits for commands via this stream. When it receives some data (commands), it notifies the NXJApp, perhaps through a CommandListener interface.

Map Panel

The MapPanel is a Panel that has methods for adding new objects to the MapPanel. It is purely interested in rendering map data. Objects it can display are listed above in the Mapper section.

Some objects are persistent from moment to moment. For example, the map data and waypoints are drawn for every frame of "animation" on the MapPanel and there is no timestamp associated with these objects. Some objects have timestamps, such as Pose at time T, and should only be represented over a discrete series of frames (until it is updated with a newer timestamp). A particle set changes throughout the entire run of a robot, therefore the particle set should have a timestamp too and different particle sets will display at different "frames" of the animation. The MapPanel perhaps has a method draw(timestamp) which specifies which frame in the navigation sequence to draw.

Map Application

The Map Application can be either a GUI interface/command line interface written by the user, or a full-featured Map Application available in our bin directory. This application would use any of the following API classes: MapServer, CommandServer, and/or MapPanel.

The full-featured map application contained in the bin directory. It has an instance of the MapServer, CommandServer, and another class called MapGUI that is designed by a talented leJOS NXJ developer. The MapApp accepts map data from the MapServer, which it then passes to the MapGUI by calling the appropriate method of MapGUI. The MapApp accepts commands from the MapGUI (such as button clicks, etc...) and then forwards the proper commands via the CommandServer by calling CommandServer methods.

The MapGUI has a nice user interface that contains a MapPanel at the heart for display. It also has various buttons/check-boxes, option dialogs, and accepts button clicks from the MapPanel.

  • List of robots currently connected to MapServer and sending data.
  • Check boxes (an options dialog perhaps, or maybe on the main control panel) that filter which data to display. Can filter by robot too.
  • Options to save the collected data (with timestamps) to disk. Should be easy because data arrives as an InputStream and can be output as a stream to a File.
  • Option to load a data file and replay it with a slider bar for the time scale (same as PenEmuNXT).
  • Option to show/hide control aspects of the GUI, in case they just want to focus on displaying map data (not controlling a robot).

Note: I'm not entirely sure how the user could control display if a robot is currently connected and sending data. For example, what happens if a robot is currently sending data and the user loads a previous file for review? Forbid user from save/load functions while a robot is connected and sending data?

Map Sample

The sample is very basic, showing perhaps one example of displaying map data to a GUI. The sample could also show how to send waypoints to the NXT brick received by the clicks on the GUI.