Oyster LoRaWAN and Helium Network Setup
Congratulations on your purchase of the most dependable and hard working LoRaWAN GPS tracker on the market, the Oyster. Your tracking device is sold with out service, and you are required to setup the device and provide your own tracking software. However, in this guide, we will show you how to connect your new Oyster to the Helium Network and display your tracking data in Helium Cargo.
Step 1 - Connect Your Device To The Helium Network
When you receive your Oyster LoRaWAN tracking device, there will be a sticker inside the box that will give you the following items:
- DevEUI
- AppEUI
- AppKEY
Please take note of these as they are required to connect your device to any LoRa network.
Open a browser and goto https://console.helium.com From here, create an account and get signed in
Next, select DEVICES and ADD DEVICE. This will bring you to a screen that allows you to enter your device information that you collected from the sticker inside the box.
- Name – Give your device a unique name
- Dev EUI – This is from the sticker inside the box
- App EUI – This is from the sticker inside the box
- App KEY – This is from the sticker inside the box
- Attach A Label – Leave this blank for now
After you add your first device, you will be brought back to the DEVICES screen. From here, click on your new device. I named my device “Test Oyster”.
You can see on the right, that this device has NOT transferred any packets across the Helium network.
Next, open the Helium Console Debugger. That is the black icon on the right, that looks like a “bug”.
Now, we can watch the data in real-time as it moves through the network.
So go ahead and insert 3 AA batteries into your Oyster GPS tracker now.
You should see a RED LED begin to flash inside the Oyster, and shortly after, you should see some activity in the Debugger.
Congratulations! Your device is now connected to the Helium Network. In this image, you can see the Join_Accept message which tells us that the device was successfully connected.
Step 2 - Decode the Payload
Now that we are sending data to the Helium Network, we need to decode it. LoRaWAN has a very small payload size, and because of this, we must encode the data to make it small enough to be sent.
We will start by creating a new Helium Function. Please click on FUNCTION, then ADD FUNCTION.
Pick a unique name, select DECODER and select CUSTOM SCRIPT. Next, copy the Helium Function from below and paste it into the Helium Function on the Helium Console.
Lastly, under the Helium Function, you can assign a label. Type in “Oyster” and click ADD. Now click SAVE FUNCTION.
Helium Function:
function Decoder(bytes, port)
{
// Decode an uplink message from a buffer
// (array) of bytes to an object of fields.
var decoded = {};
if (port === 1)
{
decoded.latitude = bytes[0] + bytes[1] * 256 + bytes[2] * 65536 + bytes[3] * 16777216;
if (decoded.latitude >= 0x80000000)
decoded.latitude -= 0x100000000;
decoded.latitude /= 1e7;
decoded.longitude = bytes[4] + bytes[5] * 256 + bytes[6] * 65536 + bytes[7] * 16777216;
if (decoded.longitude >= 0x80000000)
decoded.longitude -= 0x100000000;
decoded.longitude /= 1e7;
decoded.accuracy = 1;
decoded.altitude = 0;
}
else if (port === 2)
{
decoded.type = "downlink ack";
decoded.sequence = (bytes[0] & 0x7F);
decoded.accepted = ((bytes[0] & 0x80) !== 0) ? true : false;
decoded.fwMaj = bytes[1];
decoded.fwMin = bytes[2];
}
else if (port === 3)
{
decoded.type = "stats";
decoded.initialBatV = (((bytes[0] & 0xF) !== 0) ? (4.0 + (bytes[0] & 0xF) * 0.100) : null);
decoded.txCount = 32 * ((bytes[0] >> 4) + (bytes[1] & 0x7F) * 16);
decoded.tripCount = 32 * ((bytes[1] >> 7) + (bytes[2] & 0xFF) * 2
+ (bytes[3] & 0x0F) * 512);
decoded.gpsSuccesses = 32 * ((bytes[3] >> 4) + (bytes[4] & 0x3F) * 16);
decoded.gpsFails = 32 * ((bytes[4] >> 6) + (bytes[5] & 0x3F) * 4);
decoded.aveGpsFixS = 1 * ((bytes[5] >> 6) + (bytes[6] & 0x7F) * 4);
decoded.aveGpsFailS = 1 * ((bytes[6] >> 7) + (bytes[7] & 0xFF) * 2);
decoded.aveGpsFreshenS = 1 * ((bytes[7] >> 8) + (bytes[8] & 0xFF) * 1);
decoded.wakeupsPerTrip = 1 * ((bytes[8] >> 8) + (bytes[9] & 0x7F) * 1);
decoded.uptimeWeeks = 1 * ((bytes[9] >> 7) + (bytes[10] & 0xFF) * 2);
}
return decoded;
}
Great! Now we need to assign the Oyster function (decoder) to your device, and test it. So click on DEVICES on the left, and then click on your new Oyster.
Under the Device Details, you will see a section about labels. No labels are currently attached. Please click on ATTACH LABEL. In the drop down box, you can select the label you created above. In my case, I called it “Oyster”.
Now lets test the decoder… In the console, go back to your Debugger. Next, remove and re-install the batteries in your oyster.
From the debugger, you can see multiple uplinks. After GPS gets a fix, we can expand the Debug Request to see the decoded payload. Here is the lat and long information from our Oyster GPS tracker.
Next, lets push our decoded data over to Helium Cargo so we can display the location of our GPS tracker on a map.
Select INTEGRATION on the left hand menu. Next, select HELIUM CARGO.
Please read through the agreement, and if you accept, please click I AGREE.
Under that, specify a name. I am just going to use “Cargo”
Next, select the label from earlier. In my example, I used “oyster”.
Finally, select “Add Integration”
Next, load Helium Cargo.. http://cargo.helium.com
As soon as you install batteries into the device and it obtains a GPS fix, you should see your device show up on the map.
In my case, I named my device “Test Oyster” in Helium Console. So when I filter the results by my device name, I can see my 1 device show up.
That’s it for the most part. You now know the fundamentals for getting the Oyster LoRaWAN to send data via the Helium network to a server of your choice. If you are looking for a professional GPS tracking software package, LoneStar Tracking offers this for a low monthly fee. This will give you access to a mobile app and historical data. Helium Cargo is a great free option, but it is very limited as you can tell.
Another cool project that you may want to look into is the Helium Mappers project, available at http://mappers.helium.com You can add a new integration in Helium Console, and send data to the Mappers Project. This is a way to help the community plot coverage data.