Getting Started with CHARIOT

Most Helpful Article Most Viewed Article

If you're interested in trying out the CHARIOT product you've come to the right place! This article will take you through a series of steps that will allow you to see CHARIOT in action.

First of all, if you haven't read Introduction to CHARIOT you should go there now and read the article. Otherwise you might have a hard time understanding what you're trying to accomplish.

In this Getting Started article we will do three main things:

  • Set up a Product in the Developer Portal
  • Create a simulation of the Product using Ubuntu
  • Use a mobile app to access the Product from a remote network

In a normal scenario there are two main components involved. The first is the XMPP Connector product. This is usually your main product or appliance that you will sell to customers. We will call this the Direct Product. The second is the mobile app. This is an app on a mobile or tablet device that customers will install to interact with your product. We will call this the Connect Product. While there are other use cases, this is the most common and will thus be the focus of this article.

Note that we call both of them "Products". In a commercial release both will be produced by your organization. For now, though, the Connect Product will be the CHARIOT Join app. We will focus mainly on creating the Direct Product so that you can see how CHARIOT can empower your IoT device.

NOTE: We recommend that you read through and follow this article from an Ubuntu 14.04 system. If you don't have an Ubuntu system you can download a pre-built Ubuntu 14.04 VirtualBox VM, with all of the requisite packages pre-installed, by clicking here.

Creating a Product

First, log in to the Developer Portal. Once in the Developer Portal, select Products in the left sidebar, then click the Add Product button in the top-right corner as shown below.

Enter the information for your product in this dialog.

Name your product something that makes sense. If you are planning on creating an IoT gateway, for instance, you may want to name it "IoT Gateway". Other good names may be actual product names or internal code names for your product. This information won't be seen by the public, so the main thing is to name it something descriptive that helps you and others recognize which product this is.

For this product we'll be creating a "Direct" product. This means that your product will be able to bridge the entire local AllJoyn network to the mobile app. This is particularly good for something like an IoT gateway device. So select "Direct" from the drop-down.

The description field is just another field that helps you describe your product for future reference. Put whatever you want in there.

Once this is done click on the "Save" button. The dialog will close and you will see the new product on the main products page. Note the Product ID field in the list. This is the unique identifier of your product. You will use this in your product to identify it, and we will use it in this article to show you how.

Set up the XMPP Connector

The next step is to create your product. In this stage we will be helping you to create a simulation of your product by installing and running the AllJoyn XMPP Connector. All of the following should be done on an Ubuntu 14.04 system. If you have one already we recommend you use that. Otherwise you can download a VirtualBox VM with all of the requisite packages pre-installed.

Go here if you plan to use the VM and you haven't yet downloaded it. If you are using the VM then you can skip the next section and go to the Get the latest XMPP Connector section.

Add the apt repository

Append the line deb trusty main to the /etc/apt/sources.list file as follows:

echo 'deb trusty main' | sudo tee -a /etc/apt/sources.list

Then add the certificate for the apt server to your system:

sudo apt-key adv --keyserver --recv-keys 96AAA3BF

This allows your Ubuntu system to pull the necessary packages from the CHARIOT server.

Get the latest XMPP Connector

From the terminal type sudo apt-get update to update your local apt database with the latest information from the CHARIOT apt server.

sudo apt-get update

Now type sudo apt-get install alljoyn-xmppconn to install the latest version onto your Ubuntu system.

sudo apt-get install alljoyn-xmppconn

You should now have the latest AllJoyn XMPP Connector and its dependencies, as well as some AllJoyn sample apps, on your Ubuntu system. You can check by typing which xmppconn in the terminal.

which xmppconn

Configure xmppconn

In the terminal navigate to the /etc/xmppconn folder and then open the xmppconn_factory.conf file as superuser to edit it.

sudo gedit /etc/xmppconn/xmppconn_factory.conf

Copy the ProductID from the Developer Portal into your copy buffer (usually CTRL+c). As mentioned before, the ProductID can be found in the Developer Portal under the entry for the product you just created.

Paste the ProductID into the ProductID field in the xmppcon_factory.conf file that you just opened.

You also need a SerialNumber for your product. You can type any alphanumeric string in that field for now. But be aware that it must be a unique serial number. When you try to register more than one device with the same serial number the server will return an error. This will happen during the pairing sequence that we discuss later.

The file looks like the following:

 "ProductID": "Your Product ID",
 "SerialNumber": "Your Serial Number",
 "DeviceName" : "My Device Name",
 "AppName" : "AllJoyn XMPP Connector",
 "Manufacturer" : "My Manufacturer Name",
 "ModelNumber" : "My Model Number",
 "Description" : "Description of my device",
 "DateOfManufacture" : "1970-01-01",
 "SoftwareVersion" : "0.0.1",
 "HardwareVersion" : "0.0.1",
 "SupportUrl" : "",

Save and Close the file. You are now ready to connect the xmppconn service with the mobile app.

Before you start xmppconn you need to make sure the AllJoyn Daemon is running.

sudo service alljoyn start
sudo service alljoyn status

The start command starts the alljoyn service, and the status command verifies that it's running. It should say something like this:

Checking alljoyn...     Running, the PID is 12345

Now start the XMPP connector and make sure it's running:

sudo service xmppconn start
sudo service xmppconn status

You should see the same thing as with the alljoyn service:

Checking xmppconn...     Running, the PID is 45678

If you don't see this then you should check the log under /var/log/xmppconn.log to see what is wrong.

Connect the CHARIOT Join Mobile App

On an Android mobile device or tablet you can download the CHARIOT Join app from Download and install the app onto your mobile device. You may have to enable "Install from unknown sources" in your Android device settings.

NOTE: The CHARIOT Join app will soon be available on the Google Play Store.

Once it is installed create a CHARIOT Mobile account (or sign in if you already have one).

NOTE: This is not the same account as your developer account that you used on the Developer Portal website. It is an end-user account. That is, when your organization releases a mobile app that uses CHARIOT, end-users of your mobile app will create a subscriber account to log in to the CHARIOT service. In your mobile app this account can be created several ways as described in the documentation for the Mobile SDK.

Connect the mobile device to the same LAN (local area network) as the system that runs XMPP Connector.

Once the mobile device running CHARIOT Join is on the same local network as the system that runs the XMPP Connector you can start the XMPP Connector from the terminal:

sudo service xmppconn start

The XMPP Connector should show up in the list on CHARIOT Join. Unless you changed the name in the xmppconn_factory.conf file it should be listed as "My Device Name".

You can now pair the CHARIOT Join app with the XMPP Connector by pressing the "Pair" button. This process of pairing does several things:

  • Registers the Direct device (that runs XMPP Connector) with the server
  • Creates XMPP accounts on the server
  • Connects the CHARIOT Join app with the XMPP Connector over XMPP

Once that process is done the devices will be able to communicate on each other's AllJoyn buses when they are not on the same local network as if they still were. This means that any of the AllJoyn services that are running on the local network will be accessible remotely from your mobile app.

Control your AllJoyn Services Remotely

Now that you have your mobile device connected to your Ubuntu system via CHARIOT, the next step is to see first-hand how CHARIOT extends your AllJoyn bus. Any AllJoyn service should work, but we will start by using simple AllJoyn Control Panel apps between your mobile device and your Ubuntu system.

Install the Dashboard app

On your mobile device install the Dashboard app. You can download it from You may have to enable "Install from unknown sources" in your Android device settings to install this app.

Go ahead and open the Dashboard app on your device.

NOTE: It is possible to get the Dashboard app from other sources, but we recommend you download it from our servers. We have updated it with bug fixes and have added AllJoyn 15.04 support (the latest in the public repository is 14.12).

Run the Ubuntu Control Panel Sample

Next you need the Ubuntu version of the Control Panel sample. This can be built manually, but it's easier to download it from the CHARIOT apt repository. So from the terminal on your Ubuntu system, type the following:

sudo apt-get install alljoyn-services-binaries

You now have the ControlPanelProducer program installed as well as other handy AllJoyn samples. Run the ControlPanelProducer sample program from the terminal by typing:

sudo /opt/alljoyn/services/15.04/controlpanel/ControlPanelProducer

This will run a mock oven service that will be seen on your mobile device. After running the program look at it in your Dashboard app. You can now interact with this fake oven from your mobile device.

Change networks on the mobile phone

Now that you have these two devices communicating with one another locally over AllJoyn, the next step is to try it remotely using the CHARIOT service. To do this you need to connect to a different WiFi network than the one that the Ubuntu system is on. NOTE: When you use the CHARIOT Mobile SDK inside your mobile app you are able to turn off WiFi and use the device's cellular data plan. However, a WiFi network is required for CHARIOT Join to work because the Android application sandbox prevents the AllJoyn buses in separate apps from communicating directly.

Once you are no longer connected to the Ubuntu system's network the CHARIOT platform starts its magic. The Join app will connect to the XMPP Connector on the Ubuntu system through the CHARIOT cloud service. You can see evidence that it has connected remotely because the icon on the right side of the "My Device Name" list item will change from 'local' to 'remote'.

Now continue changing the settings of the mock oven from the mobile app. It still works!

Build your own device

You just saw the CHARIOT service in action through a simple Control Panel service. But CHARIOT enables all AllJoyn services and interfaces. If you already have an AllJoyn-enabled mobile app and an AllJoyn-enabled product, we encourage you to try those now alongside the XMPP Connector and CHARIOT Join and see how it works. Assuming you are using standard AllJoyn it should work perfectly.

If you don't yet have an AllJoyn-enabled product, we recommend that as you build it you use the CHARIOT service as your gateway to take your device outside the local network.

Either way we aim to help you as you continue to improve your AllJoyn products. Feel free to ask questions or contribute to our Community Questions and Answers Forum.

Rate This Article

(3 out of 3 people found this article helpful)