Skip to content

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.

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:

RI control flow

The client can send messages to the PTV Navigator for two different main purposes:

  • Messages which will trigger immediately an action in the PTV Navigator, such as Start a navigation or Geocode a given address (retrieve the position). The PTV Navigator will always send back an acknowledgement message and in some cases, it returns data like the result of a geocoding. These sent back messages will be received in the client software in the Handler implementation.

  • Messages which will tell the PTV Navigator that the client wants to listen to some events, like gps information. In this case, the PTV Navigator will send back frequently information until the client sends a message that the listening should stop.

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 Geocode 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

variables

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

detailed

Some messages, like the geocode message, need data to be sent to the PTV Navigator. In the "Sending bundle" section, the keys and values needed and their types are listed:

sending bundle

Some messages return data, which is described in the "Returned bundle" section:

returned bundle

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:

returned errorcodes

Attention

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

Next steps

To find out more, see the Tutorial page.