This tutorial can be used with three (3) types of boards: Adafruit HUZZAH ESP32 Feather or Sparkfun ESP32 Thing or Expressif ESP32 DevKitC V4 (shown below, left to right).
By connecting any one of these boards to Medium One’s Prototyping Sandbox, you can control its LED and get your geolocation data. For the purposes of this tutorial, we will use the HUZZAH ESP32 board.
In this Quick Start Guide, you will:
- Set up an Arduino environment
- Program the HUZZAH ESP32 Feather board
- Use Medium One Workflows to produce geolocation data and switch the LED on and off
- Use the Medium One IoT Controller mobile app to control the LED and view your location on a map
Here’s what you need to get started:
- Medium One Prototyping Sandbox Account [Buy M1-IOT-PROTO]
- Option 1: Adafruit HUZZAH ESP32 Feather [Buy-3405]
- Option 2: Sparkfun ESP32 Thing [Buy-474-DEV-13907]
- Option 3: Expressif ESP32 DevKitC V4 [Buy-356-ESP32-DEVKITC]
- CP2104 USB Driver [download]
- Windows PC or Mac OS
- Note: this tutorial is based on Windows
- 4 GHz WiFi Internet Access
- Medium One IoT Controller Mobile App [download]
- Arduino IDE [download]
Step 1: Set up your Medium One Prototyping Sandbox Account
Click “Setup” in the left-hand sidebar of your Medium One account. Go to “MQTT” and copy down your PROJECT MQTT ID for later use.
Go to “Manage Users” and click “Add New User”.
Give your new device a USERNAME and PASSWORD. You will want to copy these down for later use as well. Then click “Save”.
You will also want to copy down the USER MQTT ID that shows up after you click Save.
Go to “Manage API Keys”, click “Add New API Key”, give your API Key a description, and click “Save”. You will want to copy down the API KEY for later use.
Step 2: Set up the Mobile App
Note: These instructions are for the IoS app, but the Android app is similar.
Open the IoT Controller app and click on the plus (+) sign in the top right corner.
Now you can give your project a name and input your Username, Password, and API Key from the account set up. Then press “Done”.
If you entered it correctly, you should see a green check box beside API login.
Next, press “+Add New Widget”.
Select “Switch”. Press the power icon on the left-hand side of the switch to access the settings.
Type “raw” for the stream, and “switch” for the tag. Then press “Done”.
Press “+ Add New Widget” again and scroll down to the bottom to select “Map”.
Press the marker icon on the left-hand side of the map and type “processed” for the stream and “gps” for the tag. Then press “Done”. Note: you will not see the location of the device yet.
Now press “Save” at the bottom of the app. You should get a confirmation that it was saved.
Go to your Medium One account and go to the “Dashboard” on the left-hand sidebar. Click “Single User Real Time Events Stream”.
Select your user in the right hand corner of the widget.
Now, on the app, click on the switch to turn it on.
You should see an event show up on the widget.
Click the save icon (floppy disk) in the top right corner of the dashboard.
Step 3: Set up the ESP32 Board
Click on Instructions for Windows
And follow the instructions.
Go to Tools -> Board:”Adafruit ESP32 Feather”
Go to Sketch -> Include Library -> Manage Libraries.
Copy and paste the following code from the link below into your project.
NOTE: If you are using the Expressif board, add one extra line of code that is commented out. You’ll find the following code right after the INTRO comments.
//Uncomment this line below if Expressif ESP32 DevKitC v4 is used because
//this board does not have a user LED. An external LED is used and connected
//to GPIO pin 16.
//#define LED_BUILTIN 16
Fill in your Sandbox and WiFi credentials where indicated by replacing <Project MQTT ID>, <User MQTT>, <API Key>, etc. You will find these near the top portion of the code as shown below:
After replacing the code with your credentials , it should look something like this:
Step 4: Install USB Driver
If this is the first time the board is being used on your PC, you will need to download and install the CP2104 USB Driver (download link provided at the start of this guide). This is needed for the board to communicate with the PC via USB. Also make sure to use a USB cable that supports data (not power only).
Step 5: Programming the Board
Connect your board to your PC via USB. This is HUZZAH ESP32 board. Connecting the other 2 boards are similar.
Next, go to Tools -> Port. If the board is properly connected and the USB driver is installed, you’ll see *SLAB_USBtoUART device listed. Note, on Windows, you’ll need to select the correct com port.
Then click on the upload arrow in the top left corner to compile and flash the board, this may take a few minutes
Note the output log during this step to see when it’s completed.
Once complete, go back to your Medium One Dashboard, where the Real Time Events Stream should be open. You should eventually receive an event from your board within a minute.
Go to Tools -> Serial Monitor to see print statements from the board indicating when the board connects to the WiFi.
Now change the baud rate to 115200 in the lower right corner (see below).
You will also receive a heartbeat event from the board every minute.
Unplug your board.
Step 6: Write Workflow 1 – Switch LED
Go to “Config” from the left-hand sidebar on your Medium One account and click “Data Streams”.
Click “raw” and then click the active checkboxes next to “ip_address” and “switch”. Then click “Save Data Stream”.
Now go to your Workflow Studio on your Medium One account and click “Create”.
Give your workflow a name. We named ours “switch led”.
Click the “Tags and Triggers” icon, which is the first icon on the right-hand sidebar.
Click “raw” and drag the “switch” tag into the main area of the workflow.
Now click on the “Modules” icon (the second icon in the sidebar), click on “Foundation” and drag a “Base Python” module into the workflow.
Connect the bottom end of the switch tag to the “in1” circle on the Base Python module.
Double-click on the Base Python module and copy and paste the following code into the Script section, replacing any code that is originally there.
led_value = IONode.get_input('in1')['event_data']['value']
send_value = "0"
if led_value == "on":
send_value = "1"
Now click “Save and Activate”.
Plug the board in and open the IoT Controller app.
After the board is done setting up (within a minute), turn your switch on the app on and off. You should see the LED on the board turn on (RED light first photo) and off (second photo).
Unplug the board.
Step 7: Write Workflow 2 – Get Location
Create a new workflow, name it, and drag the raw ip_address tag into the workflow.
Drag a Base Python module into the workflow.
Click the “Outputs” icon (third icon on sidebar) and drag two “Processed Stream – Single” outputs into the workflow.
Double click on the Base Python module and click “Inputs/Outputs”. Then click “Add Output”.
Copy and paste the following code into the Script area, replacing any code that was previously there. Then click “Save”.
# get IP from event
ip_address = IONode.get_input('in1')['event_data']['value']
geo_data = M1Geolocation.get_location_from_ip(ip_address)
# update device gps data
geo_point = str(geo_data['location']['latitude']) + " " + str(geo_data['location']['longitude'])
# save gps data separately to be used for the maps
log("Failed to get IP lookup")
Now connect the Base Python module to its input and outputs as shown in the picture.
Now click on the “Revisions” icon (second from the bottom of the sidebar).
Click the checkmark under the latest revision to activate the workflow if it’s not activated.
Go to your Dashboard and plug in the board.
In addition to the board event, you should get two GPS events in your Events Stream.
Step 8: Map Location
Click “Config” and then “Data Streams” on the left-hand sidebar. Then click “processed”.
Look for “processed.gps” and change the type from “GeoPoint – Time Series” to “GeoPoint – Last Value”.
Then press “Save Data Stream”.
Go back to your Dashboard, and add the Single User GeoPoint Chart.
After selecting your user, you should see your general location marked on the map. Since it is based on ip address, it is not 100% accurate.
Also, if you open up your IoT Controller app, you will see this point marked on your map widget.
Congrats! You have finished the tutorial. If you’d like to try a real world example using the ESP32, checkout [RFID Card Reader Tutorial].
Or learn more about the Medium One Sandbox and all its capabilities here [Medium-One-Docs].