Walkthrough

Overview

This page aims to provide a simple step-by-step walkthrough of using Copilot Control.

Example - Using a BMP280 Sensor

In this scenario, we want to use the BMP280 sensor, which provides Temperature, Pressure, Humidity, and estimated Altitude.

We want to use this sensor to create Custom Messages which are transmitted by Jetpack, and displayed on the Dashboard.

Step 1 - Wire up BMP280

The BMP280 sensor uses I2C, so we want to interface that with Jetpack.

The Hardware Hookup page describes how to interface to I2C sensors and power them, so we wire up the sensor accordingly.

Step 2 - Open Copilot Control

Open the Tracker GUI, connect, and select a time slot to send your message.

We will use Slot 3.

Open the Copilot Control panel by clicking the button on the GUI. Slot 3 is open by default.

Step 3 - Design the Custom Message

We know the BMP280 can measure:

• Temperature
• Pressure
• Altitude (estimated)

Let's transmit all of those in a Custom Message.

Designing our message means being specific about what exactly we're sending.

For example, the Temperature field -- let's decide:

Property	Decision	Note
Unit	Fahrenheit	A commonly understood unit of temperature.
Lowest value expected	-50	Trackers don't really see temperatures less than this.
Highest value expected	85	Useful to see real temperature on the ground while testing also.
Resolution of value	1 degree	1 degree increments seems fine.

We enter these specifics, into the Copilot Control's Editor for Slot 3 to define this Custom Message. We do the same for the other fields as well.

Message Definition used (copy this)

{ "name": "Temperature", "unit": "Fahrenheit", "lowValue": -50, "highValue":    85, "stepSize":  1 },
{ "name": "Pressure",    "unit": "MilliBars",  "lowValue":   0, "highValue":  1013, "stepSize":  1 },
{ "name": "Altitude",    "unit": "Feet",       "lowValue":   0, "highValue": 50000, "stepSize": 20 },

Make sure to save!

The Message Definition part of the configuration window now looks like this:

Step 4 - Use JavaScript to fill out the Custom Message

Defining a message does nothing on its own. The message fields (eg Temperature) need to be given a value before the message is sent.

Jetpack lets you define the message fields AND the values (using JavaScript).

JavaScript lets you operate the BMP280 sensor to take measurements, and set the Custom Message field values with those measurements.

JavaScript used (copy this)

// get sensor
let bmp280 = new BMP280(0x77)

// fill out custom message temperature
msg.SetTemperatureFahrenheit(bmp280.GetTemperatureFahrenheit())

// fill out custom message pressure
msg.SetPressureMilliBars(bmp280.GetPressureMilliBars())

// fill out custom message altitude
msg.SetAltitudeFeet(bmp280.GetAltitudeFeet())

Make sure to save!

Run the code to test it is working.

This tests how it would work during flight. The code is operating the sensor right now, and filling out a Custom Message that would be sent if this were flying.

You are automatically shown the values that are set in the Custom Message.

The JavaScript part of the configuration window now looks like this:

Step 5 - Save your configuration to your computer

Each time we saved our work above, it was saved to the tracker, not to our computer's hard drive.

We can save to our computer now.

Collapse the Slot 3 pane by clicking its name.

Then click the "To File (Bulk)" button. Save your configuration with a name that matches your flight.

Step 6 - Get a link to your flight

The Dashboard needs the Message Definition to decode the data.

The GUI provides a link that opens the Dashboard with the Message Definition pre-configured (stored in the URL).

Bookmark this URL for easy access later.

Step 7 - Done

You can now close any configuration windows and disconnect from the tracker.

You're now ready to do all the testing you would normally do to prepare for a flight.

Example Explained

The above is a quick walkthrough without much context.

Here a bit more detail is added to help explain how it works.

Sending Custom Messages

Before you can send a message, you need to describe that message so Jetpack knows how to send it.

Describing a message is done using a Message Definition (describe field names, units, values, etc).

This is done in JSON format, which has structure and is also easy to read.

Take the following example Message Definition as a starting point.

Example Message Definition

{ "name": "Temperature", "unit": "Fahrenheit", "lowValue": -50, "highValue":    85, "stepSize":  1 },
{ "name": "Pressure",    "unit": "MilliBars",  "lowValue":   0, "highValue":  1013, "stepSize":  1 },
{ "name": "Altitude",    "unit": "Feet",       "lowValue":   0, "highValue": 50000, "stepSize": 20 },

How a Message Definition works

Each row/line is a Field. All the Fields, together, are a Message.

The message is sent and received all at once, so receivers have access to all the data in that message.

Above, we see a Message with 3 fields. Each field has its own unit and range of numbers it can be set to.

Now, consider this code, which "fills out" a message field with data.

Example JavaScript for setting a Message Field's value

// get sensor (1)
let bmp280 = new BMP280(0x77)

// fill out custom message temperature (2)
msg.SetTemperatureFahrenheit(bmp280.GetTemperatureFahrenheit())

1. Lines that start with // are comments to help you read the code.
2. Filling out a message involves "Setting" its value. The value can come from "Getting" a measurement from a sensor.

Let's look more carefully at the above code

Lines that start with // are comments and notes to help you read the code.

Filling out a message field involves "Setting" its value. The value can come from "Getting" a measurement from a sensor (or other ways).

msg.SetTemperatureFahrenheit(x) is saying, set the Custom Message TemperatureFahrenheit field to the value x.

In the code above, x is the result of bmp280.GetTemperatureFahrenheit(), which retrieves a temperature measurement from the BMP280 sensor.

With the above code, you have successfully used the BMP280 to take a measurement and store it in the TemperatureFahrenheit field of the message.

When the JavaScript is complete, the message is filled out, and will then be sent by the tracker.

The fields you can set on msg depend on what your Message Definition is!

In the Message Definition above, you have a field named Temperature which has the unit of Fahrenheit.

Because of that, you can automatically call msg.SetTemperatureFahrenheit(x) to set the value of that field to x.

This applies to every field in the Message Definition.

All fields are "clamped" to their defined range, so no need to check the values you're setting fall into that range, it's handled automatically. For example, if you call msg.SetTemperatureFahrenheit(100), then the actual value set will be 85 (the maximum defined in the Message Definition).

You can also "Get" the values back from the message, such as by msg.GetTemperatureFahrenheit(), such as for Logging, or setting other variables, etc.