First Steps

The remote interface is a way to communicate with the PTV Navigator software and to remotely control some the of it's functionality, such as adding stations and starting a navigation from an activity outside the PTV Navigator itself. This is done by sending messages between the PTV Navigator and the client software. On this page we will describe the principles of the communication between the PTV Navigator and a client and what is needed to get this communication working. In the Tutorial, we will later show in detail how the connection will be established and how to trigger actions in the PTV Navigator with many code examples.

Attention

On devices using Android 10 (API level 29) and above, be sure to set the popup permission in the application permission settings. If you don't set it, the app will not come to foreground and some API functions will not work properly.

Attention

Please note that the Navigator G2 returns by default results in a compatible mode to the previous Navigator remote interface. We highly recommend for future implementations to deactivate this compatible mode by sending the command 'MSG_RI_SET_COMPATIBILITY_MODE' with the parameter 'CompatibilityMode' set to false. With the compatibility mode set to 'false', the returned result offers more information than the compatible one.

What you need

• An Android device with a running PTV Navigator on it
• Android Studio
• A basic knowledge of Java and the Android framework

---

Basics

The technique we use to let other applications communicate with the PTV Navigator is based on an android service (android.app.Service). The navigation software starts such a service and clients can connect to this service (this is called binding). After binding, clients can interact with the PTV Navigator by sending messages to the service and the service itself can send messages back to the client, like acknowledgement messages or messages with data like gps information.

First of all, we describe the different classes of the Android SDK we need to get a connection to the service. Later on, we will see how they are actually be used.

The different classes are:

Service (android.app.Service):

A service is a component of an application that can communicate with activities outside it's own one. It runs in the PTV Navigator application.

ServiceConnection (android.content.ServiceConnection):

To communicate with such a service, a client application has to bind itself to that service, so a connection between both can be established. This is done by the ServiceConnection.

Messenger (android.os.Messenger):

When the service binds to the ServiceConnection, it will call a method of the ServiceConnection, which you have to overwrite (the method is called onServiceConnected()). In this method, a so called Messenger will be set. Over this Messenger you can send later on messages to the service. You will need two Messengers, one to send messages from the PTV Navigator to the client and one for the other direction.

Handler (android.os.Handler)

To receive messages from the PTV Navigator, the client has to implement a Handler which will be called every time a new message arrives.

Message (android.os.Message):

The actual object, that is sent between the service and the client software and vice versa.

Bundle (android.os.Bundle):

The Bundle holds optional data (it serializes it) and can be attached to a Message.

Sending and receiving messages

As we stated before, the PTV Navigator starts a service, and we can bind with the above classes to this service. How this is done in detail, we will show in the Tutorial. After binding to the service, we need these objects for sending a message:

• a Messenger to communicate with the service,
• a Messenger to let the service communicate with the client,
• a Message for sending and
• a Handler for getting the messages from the service.

The picture below shows the control flow of sending and receiving messages:

The client can send messages to the PTV Navigator like Messages which will trigger immediately an action in the PTV Navigator, such as Start a navigation or Get all vehicle profiles. The PTV Navigator will always send back an acknowledgement message and in some cases, it returns data like all vehicle profiles available. These sent back messages will be received in the client software in the Handler implementation.

API reference howto

To know how a command works, take a look at the API reference for a certain message. As an example, we will take a look at the Add Station documentation to give you an overview how the documentation is built up: First, we find the message id, which is needed for sending a message to the PTV Navigator in the "Variables" section:

Variables

Next, an overview of the functionality of the command is given in the "Detailed Descripton" section:

Add a station to the station list.
Adds a station with the given name and position (in geodecimal format) to the station list. Please note that stations can not be added in some situations: During an active navigation -> please stop the navigation by using the Stop the current running navigation message and then try again to add stations.

Some messages like the add station message need data to be sent to the PTV Navigator. In the "Sending bundle" section, the keys and values are listed with their corresponding type:

Some messages, like the Get all vehicle profiles message return data, which is described in the "Returned bundle" section:

When the PTV Navigator return a message, it always has an error code set to determine if the command succeeded or not. The return values for a certain message can be found in the "Returned Errorcodes" section:

Attention

Always check this errorcode, otherwise you don't know if the command succeeded!

Next steps

To find out more, see the Tutorial page.