API Sample Requests

Home / Portfolio / Content / Technical Writing / IoT Developer Kit / API Sample Requests

Introduction

This document lists all available API calls, parameters, errors, and responses for the various sensors and devices on the IoT Developer Kit.

Prerequisites

• The T-Mobile DevEdge IoT Developer Kit.
• A computer with Windows, macOS, or Linux OS installed.
• A serial app like Tera Term, PuTTY, Picocom, or Serial installed on your computer.

Some Important Things to Note

• Many of the API calls will require that you connect to the T-Mobile DevEdge IoT Developer Kit via command line interface (CLI). The section below called How to Connect to the Kit's CLI will show you how to connect to command line.
• Many of the API responses will be in a raw data format.
• Some of the API responses will be in JSON.
• Some of the sensors / devices will not respond with raw data or JSON at all. Instead the API call will simply change the state of that sensor / device.

• You can obtain a list of all devices that can be accessed on the IoT Developer Kit by typing device list then pressing Return on your keyboard at CLI.

  

How to Connect to the Kit's CLI

1. Connect your IoT Developer Kit using the USB-A to USB-C cable provided to your computer like in the screenshot below. Ensure that the J-Link USB-C Debug port (port on the right) is plugged into your computer.

   

2. Open your serial app on your computer. For demonstration purposes we will use Serial on a Mac.

3. Select the serial port that is connected to your IoT Developer Kit then click Open.

4. Under Terminal > Settings > Line Settings > Baud Rate make sure the following values are set then click OK:
   1. Baud Rate / Speed - 9600
   2. Data Rate - 8
   3. Parity - None
   4. Stop Bits - 1

   5. Flow Control - None

      

5. At the command line screen press Enter on your keyboard. The uart command prompt appears. To learn more about uart, please read the document Interacting with the Kit at CLI via tmo_shell.

   

Devices and Sensors

Accelerometer

To get the raw API data for the accelerometer sensor, follow the steps below:

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter sensor get LIS2DW12 (for tmo_shell version 1.15.0 or less) or sensor get lis2dw12@18 (for tmo_shell version 1.16.0 or greater) then press Return on your keyboard. Note that the device name is case sensitive. If you spell it LIS2dw12 or lis2DW12@18 you will receive a "Device unknown" error.

3. The raw accelerometer API data displays.

   

Air Pressure

To get the raw API data for the air pressure sensor, follow the steps below:

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter sensor get LPS22HH (for tmo_shell version 1.15.0 or less) or sensor get lps22hh@5c (for tmo_shell version 1.16.0 or greater) then press Return on your keyboard. Note that the device name is case sensitive. If you spell it Lps22HH or LPs22hH@5C, you will receive a "Device unknown" error.

3. The raw air pressure API data displays.

   

Ambient Light

To get the raw API data for the ambient light sensor, follow the steps below:

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter sensor get TSL2540 (for tmo_shell version 1.15.0 or less) or sensor get tsl2540@39 (for tmo_shell version 1.16.0 or greater) then press Return on your keyboard. Note that the device name is case sensitive. If you spell it Tsl2540 or TSL2540@39, you will receive a "Device unknown" error.

3. The raw ambient light API data displays.

   

Buzzer

The Buzzer sensor does not deliver a raw data or API response. Instead, you can use the buzzer to hear the T-Mobile jingle or play the buzzer at a certain pitch and for a chosen duration.

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter tmo buzzer jingle then press Return on your keyboard. Note that the syntax is case sensitive. If you type the command tmo BuZzer jinGle , the T-Mobile jingle will not play.

   

3. Listen to the kit play the T-Mobile jingle.

4. Below is a chart of commands and subcommands for the tmo buzzer.

   Command	Command Description	Subcommands	Subcommand Descriptions	Required Arguments	Example Syntax
   tmo buzzer	Actuates the buzzer to play various tones and songs.	jingle ramp tone pitch in Hz duration in msecs	Play the T-Mobile jingle. Play ramp tune. Play a tone for a time. Sets the tone's pitch. Sets the tone's duration.	jingle ramp tone <pitch in Hz> <duration in msecs>	tmo buzzer jingle tmo buzzer ramp tmo buzzer tone 880 1000

GNSS

To get the raw API data for the GNSS sensor, follow the steps below:

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter tmo location then press Return on your keyboard. Note that the command is case sensitive. If you enter tmo loCaTion, you will not receive any raw data.

   

3. The raw location API data displays.

   

LED

The LED sensors do not deliver a raw data or API response. Instead, you can change the state of the LED from on to off and set the LED's brightness. Follow in the instructions below to learn how.

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter led on pwmleds 0 then press Return on your keyboard. Note that the device name is case sensitive. If you spell it pwmlEDs, you will receive a "LED device pwnlEDs not found" error.

   

3. The white LED turns on.

   There are 4 LEDS on the DevEdge IoT Developer Kit. 0 = white, 1 = red, 2 = green, and 3 = blue.

   

4. In your serial app, enter led off pwmleds 0 to turn off the white LED.

5. To set the brightness of the white LED enter led set_brightness pwmleds 0 50 in your serial app.

   

6. The brightness of the white LED is now set to 50%.

7. Below is a chart of commands and subcommands for the LEDs.

   Command	Command Description	Subcommands	Subcommand Descriptions	Required Arguments	Example Syntax
   led	Zephyr RTOS command that allows for interaction with LEDs on the kit.	off on get_info set_brightness set_color set_channel write_channels	Turns the LED off. Turns the LED on. Not supported. Sets the brightness of the LED. Not supported. Not supported. Not supported.	<device> pwmleds <led> 0 = white LED 1 = red LED 2 = green LED 3 = blue LED	led off pwmleds 0 led on pwmleds 0 Not supported. led set_brightness pwmleds 0 50 Not supported. Not supported. Not supported.

Temperature

To get the raw API data for the temperature sensor, follow the steps below:

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter sensor get TEMP_0 (for tmo_shell version 1.15.0 or less) or sensor get as6212@48 (for tmo_shell version 1.16.0 or greater) then press Return on your keyboard. Note that the device name is case sensitive. If you spell it TEmP_0 or AS6212@48, you will receive a "Device unknown" error.

3. The raw temperature API data displays.

   

Network Operations

Modem

The modem does not deliver a raw data or API response. Instead, you can obtain more information about the modem, it's SIM card, and more. There are two options for obtaining modem information from the kit. Both are covered below.

Option 1 - Zephyr

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter modem list then press Return on your keyboard.

3. The Zephyr modem command gives you the interface ID, modem manufacturer, the model number, what version of modem firmware is installed on the kit, and the IMEI.

   

4. To learn more about the Zephyr RTOS modem command go here.

Option 2 - tmo_shell

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter tmo modem then press Return on your keyboard.

   

3. Enter tmo modem 1 imei then press Return on your keyboard to obtain the IMEI number for the kit. Note that the spelling of imei, or any of these subcommands, is not case sensitive.

   

4. Enter tmo modem 1 imsi then press Return on your keyboard to obtain the IMSI number.

   

5. Below is a chart of commands and subcommands for tmo modem.

   Command	Command Description	Subcommands	Subcommand Descriptions	Required Arguments	Example Syntax
   tmo modem	Retrieves modem and SIM data.	<iface> <cmd_str> cmd_str has the following available subcommands: imei imsi iccid ssi sim msisdn apn conn_sts ip ip6 version golden sleep wake awake psm edrx	Obtain the IMEI, or International Mobile Equipment Identity, for the kit. Obtain the IMSI, or International Mobile Subscriber Identity, for the kit. Obtain the ICCID, or Integrated Circuit Card Identification Number, for the SIM card installed on the kit. If your kit does not have a SIM card installed, you will not receive an ICCID number. Obtain the SSI, or Signal Strength Indicator, for the kit. Obtain the SIM, or Subscriber Identity Module, for the kit. If your kit does not have a SIM card installed, you will not receive a SIM number. Obtain the MSISDN, or Mobile Station Integrated Services Digital Network, for the kit. If your kit does not have a SIM card installed, you will not receive a SIM number. Obtain the APN, or Access Point Name, for the modem. Obtain the connection status, or conn_sts, for the modem. Obtain the IP, or Internet Protocol address, for the modem. Obtain the IP6, or Internet Protocol 6 address, for the modem. Obtain the firmware version for the modem. Reports whether the modem in the given system has a productized version of the modem firmware. Puts the modem to sleep. Wakes up the modem. Checks to see if the modem is awake. Puts the modem in Power Saving Mode (PSM). Puts the modem in eDRX power saving mode.	<iface> for all.	tmo modem 1 imei tmo modem 1 imsi tmo modem 1 iccid tmo modem 1 ssi tmo modem 1 sim tmo modem 1 msisdn tmo modem 1 apn tmo modem 1 conn_sts tmo modem 1 ip tmo modem 1 ip6 tmo modem 1 version tmo modem 1 golden tmo modem 1 sleep tmo modem 1 wake tmo modem 1 awake tmo modem 1 psm tmo modem 1 edrx

Wi-Fi

Wi-Fi does not deliver a raw data or API response. Instead, you can connect to Wi-Fi, scan for wireless networks, check the status of your Wi-Fi, and more. Follow the directions below to learn more.

1. Connect to your IoT Developer Kit's command line interface (CLI). Please read How to Connect to the Kit's CLI above to learn how.

2. Enter tmo ifaces then press Return on your keyboard. Based on the Data Sheet, the murata.1sc is the LTE CAT-M1/NB1 cellular modem and the RS9116W is the Wi-Fi/BLE radio device.

3. Scan for available networks by running tmo wifi scan <iface_id>.

4. Connect to a network by running tmo wifi connect <iface> "<ssid>" 0 "<psk>" or tmo wifi connect <iface> "<ssid>" if your network lacks a password.

5. If the connection is successful you should receive a "Connected" response.

6. Check the status of the Wi-Fi connection by entering tmo wifi status <iface>.

   

   You can also see that you are connected to your chosen Wi-Fi by looking at your smartphone > DevEdge IoT companion app > Home > Connectivity section.

   

Bluetooth (BLE)

Bluetooth (BLE) does not deliver a raw data or API response. Instead, you can pair your kit with an available Bluetooth device. Follow the directions below to learn more.

To enable SMP pairing enter tmo ble smp enable. After SMP is enabled if you try and pair your DevEdge IoT companion app to your IoT Developer Kit a "Connected <bluetooth_address> (random)" appears. A passkey appears as well. Enter this passkey in your smartphone's DevEdge IoT companion app.

The result on your smartphone looks like the below. Again, enter this passkey in your companion app.

To disable SMP pairing enter tmo ble smp disable.

To choose the pairing verification methodology, simply enable the relevant IO capabilities using the tmo ble smp toggle and tmo ble smp callbacks commands. For example, to test key entry on a device enable only keyboard enter the following at CLI:

uart:~$ tmo ble smp enable
SMP Enabled.
uart:~$ tmo ble smp callbacks
CONFIRM: disabled
DISPLAY: enabled
KEYBOARD: disabled
uart:~$ tmo ble smp toggle display
Display is now disabled
uart:~$ tmo ble smp toggle keyboard
Keyboard is now enabled
uart:~$ tmo ble smp callbacks
CONFIRM: disabled
DISPLAY: disabled
KEYBOARD: enabled
uart:~$

Mobile App Interface

The Mobile App Interface does not deliver a raw data or API response. Instead, you can change the status of the LEDs, buzz the buzzer, and glance at other stats like temperature and air pressure.

General

• Question 1 - What is the T-Mobile DevEdge IoT Developer Kit mobile app?
• Answer 1 - Also known as the DevEdge IoT app, this app allows the user to see "signs of life" in the kit without having to use commands at CLI.

• Question 2 - What can I do with the T-Mobile DevEdge IoT Developer Kit mobile app?

• Answer 2 - You can turn the LEDs of the kit on and off, turn the buzzer on and off, glimpse at accelerometer forces data, view not only the signal strength of the LTE-M towers near you but how many towers are near you, observe pressure and temperature readings, and note the kit's power levels. Plus, you can use the Debug tab, based on SEGGER technology, to troubleshoot your kit.

  Capability	In the Mobile App	On the Kit
  Turn LED lights on and off.	In the DevEdge IoT mobile app tap Home > I/O > Green toggle button.	The green LED lights up.
  Activate the buzzer.	In the DevEdge IoT mobile app tap Home > I/O >Activate Buzzer.	The buzzer buzzes. Unmute the video to hear the buzzer.
  Observe accelerometer forces.	In the DevEdge IoT mobile app tap the Motion tab.	Flip and turn the IoT Developer Kit and watch it move in real-time in the app.
  View LTE-M signal strength.	On the DevEdge IoT mobile Home screen view the Connectivity stats.	You must have a T-Mobile SIM card installed in order to see signal strength.
  Glimpse at air pressure data.	In the DevEdge IoT mobile app tap Home > Environment > Air Pressure.	Not applicable.
  Glance at temperature data.	In the DevEdge IoT mobile app tap Home > Environment > Temperature.	Breath on the kit and watch the temperature data change.
  Observe power levels data.		Not applicable.
  View debug logs.	Based on SEGGER technology, you can see the debug logs in the DevEdge IoT mobile app when you tap on the Debug tab.	Not applicable.

 

• Question 3 - How do I connect my DevEdge IoT mobile app to my kit?
• Answer 3 -

  1. On your smartphone, open the DevEdge IoT companion app.

     

  2. Using Bluetooth, the DevEdge IoT companion app will search for your IoT Developer Kit.

     

  3. Next, the DevEdge IoT companion app provides a list.

     

  4. Select "T-Mobile DevEdge".

  5. The DevEdge IoT home screen opens and is now populated with data from the IoT Developer Kit.

     

 

iPhone

• Question 1 - Where can I find the iPhone DevEdge IoT mobile app?

  

• Answer 1 - Open this link on your iPhone. Or do search for "DevEdge IoT" in the Apple App Store app.

Android

• Question 1 - Where can I find the Android DevEdge IoT mobile app?
• Answer 1 - Open this link on your Android mobile device. Or do a search for "DevEdge IoT" in the Google Play Store app.

 

Web App Interface

The Web App Interface does not deliver a raw data or API response. Instead you can glance at stats like temperature and air pressure.

• Question 1 - What is the T-Mobile DevEdge IoT Developer Kit Web App?

• Answer 1 - The T-Mobile DevEdge IoT Developer Kit Web App is a URL that allows you to see basic stats on your IoT Developer Kit. An example can be seen below:

  

• Question 2 - Where can I find the web app?
• Answer 2 - You can find the web app here: https://devkit.devedge.t-mobile.com.

• Question 3 - What can I do with the web app?
• Answer 3 - You can see the temperature of your kit, glimpse at its accelerometer forces data, note its LTE signal strength, and glance at a JSON data structure.

• Question 4 - How can I access / pair my IoT Developer Kit to https://devkit.devedge.t-mobile.com/?
• Answer 4 -
  1. On your computer, open a serial app like Tera Term, PuTTY, or Serial. For demonstration purposes we will use Serial on a Mac.
  2. Select the serial port that is connected to your IoT Developer Kit then click Open.
  3. Under Terminal > Settings > Line Settings > Baud Rate make sure the following values are set then click OK:
     1. Baud Rate / Speed - 9600
     2. Data Rate - 8
     3. Parity - None
     4. Stop Bits - 1
     5. Flow Control - None
        
        

        

  4. At the command line screen press Enter on your keyboard. The uart command prompt appears. To learn more about uart, please read the document Interacting with the Kit at CLI via tmo_shell.

     

  5. Enter tmo wifi connect "<SSID>" 0 "<PSK>" to connect to Wi-Fi.

  6. Enter tmo json iface 2 to set the default interface that will send the developer kit's JSON payload then press Return on your keyboard.

  7. Enter fs cat /tmo/aws_session.txt then press Return on your keyboard.

  8. Write down the number that appears just before the uart command line. This number is your 8-digit access code to the web app.

     

     This access code is case sensitive. Please ensure that you get the spelling of this access code correct or it will not work in the web app.

     

     Also note that if you receive a "Failed to obtain file /tmo/aws_session.txt (err: -2)" please contact us and we will give you instructions on how to fix this error.

     

     
     

  9. Enter tmo json enable then press Return on your keyboard.

     

  10. You should receive a 200 status code.

      

  11. In a web browser, go to the web app https://devkit.devedge.t-mobile.com/.

  12. Enter the access code then click Next.

      

  13. Look at the LTE Signal Strength section to understand your T-Mobile LTE-M network connection.

      

• Question 5 - What are the main differences between the web app and the mobile app?

• Answer 5 - Through the web app, you can view temperature, GPS, LTE, and even JSON data. A sample of the JSON data can be seen below. However, you cannot toggle the LEDs on and off and you cannot actuate the buzzer to make any sounds. These actions, however, can be taken in the mobile app. In addition, the mobile app has debugging logs, based on SEGGER technology, that allow the user to troubleshoot the kit.

  {
    "accelerometer": {
      "x": 0.210568,
      "y": 1.234696,
      "z": 9.944571
    },
    "cellSignalStrength": {
      "dbm": -103
    },
    "temperature": {
      "temperatureCelsius": 25.3
    },
    "ambientLight": {
      "visibleLux": 44.36,
      "irLux": 95.36
    },
    "pressure": {
      "kPa": 99.9
    },
    "map": {
      "lat": 47.781114,
      "lon": -122.212874,
      "hdop": 0
    }
  }    
  

FAQ

• Question 1 - Does the command modem list provide different data about the modem than tmo modem?
• Answer 1 - No. Both methods provide the same modem data.

• Question 2 - I cannot find my 8-digit access code for the web app in the box? Is there another way to find this access code?

• Answer 2 - Yes there is. At serial app CLI enter fs read /tmo/aws_session.txt. The output should provide you your 8-digit code.