Creating a TTN Application for AmbaSat

Updated: 30 Jan 2021

If you have an AmbaSat and a TTN (The Things Network) gateway, you can view raw, encrypted data as it is received using the Gateway tab of your TTN console. But since the data is encrypted, you can not interpret it. To interpret, you need to create a TTN application and a decoder.

As distributed by AmbaSat on GitHub, their example software does not yet connect to their console (as of 26 Jan 2021). And their example software is incomplete.

Michael Kamprath created an excellent, reasonably complete version of flight software for the AmbaSat that can be found here on GitHub. He also published the TTN decoder for use with the software. By creating an TTN application, you can receive and view the data sent by your AmbiSat. If you haven’t created a TTN application before, creating one can be daunting. This page contains the steps I followed to successfully create and use an app based on Michael’s code. Feel free to contact me using the Contact tab above with questions or corrections.

These instructions assume you have a free TTN account and are within range of a gateway or you have your own gateway. Should you have your own, then you already have a TTN account. Otherwise, click the “Sign Up” button of the TTN homepage and follow the instructions contained there.

  1. Log into your TTN account and select CONSOLE.
  2. Click on APPLICATIONS
  3. Click the “Add Applications” link
    1. Enter a short application id. (I entered kk6now_ambasat_v1)
    2. Enter a longer description.
    3. Select the Handler closest to your gateway.
    4. Click the “Add Application” button.
  4. Click on the “Payload Formats” Tab
    1. Delete the template code in the decoder text box.
    2. In your favorite editor, open Michael’s Payload_decoder.js code
    3. Select all and copy
    4. Paste into the decoder text box
    5. Click the Save button
  5. Click on the Devices Tab
    1. Click on the “register device” link
    2. Enter a short Device Id. (I entered kk6now_ambasat_1) NOTE: It doesn’t need to match or correspond to the application id.
    3. For Device EUI, click to crossed arrows icon to enable the EUI to be auto-generated.
    4. Click the Register button. The Device Overview screen will appear.
    5. Click the Settings tab.
    6. For Activation Method, click on ABP to select.
    7. Notice that boxes for the Device Address, Network Session Key and App Session Key will appear. These fields will be auto-generated. The values are unique to your device and application and need to be copied into the appropriate fields of your AmbaSat flight software code.
    8. Leave Frame Counter Width set to 16 bits.
    9. Uncheck the “Frame Counter Checks” box.
    10. Click the Save button
    11. Click the Overview tab (if needed to display the Device Overview screen).
  6. In the AmbaSat1Config.h file, replace the device address and key constant definitions with the values on the Device Overview screen.
    • Clicking the “eye” icon, reveals the values
    • Clicking the “<>” icon, changes the keys into C code that can be pasted into your code.
    • Clicking the “clipboard icon” at the end of the text box, copies the code into your clipboard.
  7. Click the Data tab.
  8. Compile and upload the flight software into your AmbaSat.
  9. If all works, you should see each packet appear in the Application Data window.
  10. The flight software transmits three packets at a time, once every 10 minutes. The packets are:
    • System status on port 1
    • LSM9DS1 sensor data on port 2
    • Your mission sensor data on port N (in my case, the UV sensor is on port 8)
  11. If you have a gateway, you will also see the encrypted data on the Traffic tab for your gateway.

Note 1: You can shorten the 10 minute timeout to make your debugging go quicker. In the loop() function in AmbaSat1App.cpp, find the following code:

// sleep device for designated sleep cycles
for (int i=0; i < _config.getUplinkSleepCycles(); i++)       

LowPower.powerDown(SLEEP_8S, ADC_OFF, BOD_OFF);    //sleep 8 seconds * sleepcycles
   }  

Replace _config.getUplinkSleepCycles() with integer number. I used 3 to sleep for 24 seconds, and 7 for 56 seconds. I don’t recommend anything shorter than 24 seconds.

Note 2: To operate the AmbaSat legally in the US, you need to change the frequency from 868MHz used in the EU to 915MHz used in the US. To do so, in libdeps\AmbaSat-1/IBM LMIC framework/src/lmic/config.h, comment-out the definition of CFG_eu868 and remove the comments from the definition of CFG_us915.

Note 2 corrected: This is not necessary in Michael’s code. First, the code is already configured for us915. Second, the configuration is defined in the platform.ini file. If you need to change to eu868, please make the edit there.

Note 3: Once you create an application, you need to choose a Integration should you wish to do anything with the data other than view it in real time as it arrives. A simple option to aid in debugging / testing is to use the TTN short term (7 days) Data Storage integration. The steps I used are documented here.

Note 4: Use Tago.io to create a dashboard to display your data. The procedure I used is documented here.

2 thoughts on “Creating a TTN Application for AmbaSat

  1. Fredric, thanks for putting this together. I’m sure it would be helpful for people. I have two comments on things here.

    1. On your Note 1, realize my code is enabled to accept downlinks that allows you to change the transmit cycle. Of course, if you aren’t enabling downlinks (which require enabling the external oscillator), you would have to make a code change. If you have to go with a code change, I would actually recommend that you change what PersistedConfiguration::getUplinkSleepCycles() returns rather than changing the for loop you cite. That way you keep the changes compatible with any future code updates I might make.

    2. You have note 2 wrong, at least in the context in my code base. The only changes that should be made with respect to CFG_us915 or CFG_eu868 are in the platform.ini file of the project. By defined the compile macro there, the “right thing” will happen every where else in the code, including lmic/config.h. Note that in the platform.ini file I also define the _lmic_config_h_ compiler macro. By doing this, I effectively make the contents of lmic/config.h unused. Any edits you make there are not event used by the compiler.

    I hope this makes things clearer!

    Michael

    Like

    1. Michael is correct on both counts. Regarding note 1, I was looking for a quick and dirty way to change the timing while debugging. Never use a “magic number” in production code.

      Regarding note 2, I didn’t look at platform.ini to notice that Michael effectively replaced /lmic/config.h. My note was based on the changes I made to the AmbiSat-TTN code.

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: