Carriots provides the tools to easily connect devices to the Internet and to create applications and services which integrate those devices. Status Board is an app that can be configured with different widgets to display up-to-date information on the weather, to-do lists, Twitter feeds, as well as graphs of various data all on your iPad.
When using Carriots, if you are like us, you will find that you regularly want to know if your device(s) is connected and how it is performing. To find this out, you will have to log in to your Carriots account, get into the Control Panel and then look at three different web pages to get the complete performance picture. Those pages include the device's properties, the data stream list and the status stream list. Wouldn't it be easier to just flip open your browser or iPad to see that data? YES! That is what this tutorial will help you do.
In order to work through this tutorial, you will need the following three items.
1. An account at Carriots. It is free and easy. If you like to tinker with electronics (Arduino or Raspberry Pi) and software and want to make an Internet of Things device, Carriots is a great choice for your project. There are several tutorials and a helpful forum to get started. We won't cover everything about Carriots as you can explore that on your own.
2. An account at PythonAnywhere. This will be our application server for the project. Again, it is free and because it's Python, it is only *too* easy to set up a web server. If you aren't familiar with setting up a web application, don't worry, we will walk you through it step by step. If you prefer to use PHP or Ruby or Java as your application server code, you can follow along and use our Python example code as a guide for creating your own. We will make use of Flask, a microframework written in Python.
3. Panic's Status Board app for the iPad. The app does cost money - about $10. If you don't have an iPad or don't want to pay for the app at this time, than you are still OK for this tutorial as you can view the progress and results in a web browser on any platform.
Shall we dive in?
Step 1: Set Up Your Device on Carriots
In this step we will create a new device in Carriots to monitor on Status Board. If you have an existing device, you can work through this tutorial using that device. Even if you have an existing device, we recommend reading through the rest of this step to be sure you have the device's settings configured properly.
Create a new device:
1. Login to your Carriots Control Panel.
2. Navigate to the Device List. This is found under "Device Management" menu, selecting "Devices".
3. Hit the "+New" button.
You are now on the Device Creation Page. Follow along as we fill in each of the fields. See the images to double check your work.
1. Give the device a name in the "Name" field. This is case sensitive. We used "myDevice". Remember this name, you will need it later.
2. Set a value of 5 minutes in "Data Stream Frequency", just type a 5. The default value is 1440 minutes, but that won't allow us to have an accurate status once we connect to Status Board.
3. Set a value of 10 minutes in "Status Stream Frequency". Again we use a smaller value, something that will be closer to the actual frequency of status stream posting. See below.
4. Select the time zone for your device.
5. Select your ID Group per your setup. This can be anything and isn't part of this tutorial, but is required to create a device.
Hit the "Create" button.
A bit about "Stream Frequency".
Carriots has two distinct types of streams. One is data and one is status. A Data Stream contains measurements such as a temperature reading. Status Stream is for information about your device such as its processor utilization or its firmware or maybe even battery level.
Your device, whether a real-world physical device taking measurements or a virtual device such as another program or service, will probably post data or status periodically to Carriots. For instance, your device may take a temperature reading every minute and post the data to Carriots. In this case, your Data Stream Frequency is roughly 1 minute, plus or minus based on processing and network timing. Carriots uses the value "Data Stream Frequency" to understand how your device behaves so that it can determine if the device is connected or not. In our setup, we set a value of 5 minutes. If the temperature logger stops logging, then after five minutes of no new data posting to Carriots, Carriots makes a note in the device's properties that it has no new data. This is how Carriots determines if your device is connected or not. I recommend that you usually add one or two minutes to your frequency so you don't get false disconnection alerts. If your deivce logs once a minute, use two or three minutes as your "Data Stream Frequency". The same idea applies to the Status Stream.
That was long winded, did you get all that?
You should have a device named myDevice and you should have set a value for Data Stream Frequency and Status Stream Frequency. If you wanted to configure a device to actually log data to Carriots, this is the point where you can set aside this tutorial and get your device working. But if you don't want to do that, that is OK, we will make use of Carriots' Wizard for posting test data to your account.
Next up, setting up the application server.
Step 2: Set Up a Web Application Server on PythonAnywhere
In our case, the web application has two jobs. One job is to serve web pages to Status Board (or a browser if you aren't using Status Board). The other job is to connect to the Carriots Application Programming Interface (API) to get various information about the device that is being monitored. Think of the web application as being like a telephone operator. You need a phone number, so you call the telephone operator and give them the name of the person you want to call. The operator looks up the details and then returns the phone number to you. Status Board asks our web application for details on a specific device, our web app looks it up (at Carriots) and replies. (Does anyone use telephone operators nowadays?)
PythonAnywhere has several web application frameworks you can use. We will use Flask, which is a microframework. If you aren't familiar with Flask or Python, then don't worry, I wasn't either. I've picked it up by reading and experimenting. Again, you are welcome to use other application frameworks or programming languages as well. PythonAnywhere just makes it very easy to get started.
Set up your Flask web application.
1. Create and login to your PythonAnywhere account. PythonAnywhere is abbreviated as PA or PAW throughout this tutorial.
2. In your PAW Dashboard, click on "Web".
3. Follow PAW's wizard to create a new web application. The steps are simple, all you need to do is select "Flask" when prompted with a list of Web Application Frameworks and select a location to store your files. The default location is a good choice.
4. With the web app initialized, your "Web" tab in the Dashboard should look something similar to that shown in the picture.
At this point you have a minimal Flask application established in your account. You can verify this by navigating to the application's URL. You can find this under your "Web" tab in the Dashboard. The URL will look like the following, but with username replaced with your PAW username. http://username.pythonanywhere.com/ If all is good, you should get a basic Flask Hello World style message in your web browser. It will read, "Hello from Flask!"
Well you have done it! You have a Flask web app. We told you it was easy, didn't we? Sure, it isn't customized yet. Click on over to the next step to continue building the web app. Remember, our goal is to serve data to the Status Board and to retrieve data from Carriots.
Step 3: Build Out Your Flask Web Application
In PythonAnywhere, navigate to where your web application files are stored. The folder will contain the file "flask_app.py". In this location do three things.
1. Create a new file called "CarriortsStatusBoard.py".
2. Create a folder called "templates". All lower case.
3. Go into the templates folder. Create another new file called "status.html".
So we have a couple new files and one new folder. It is these files where we will be pasting in new code. Let's paste in the code first, then go through each file to describe how the code works.
The code you need to copy/paste can be found in the three files linked below. The code you use may have been updated since the images of this tutorial were posted. Also, you might have to right click in your browser on the file link and "save as" or "Download Linked File" in order to download the file.
Open up "flask_app.py" code in your PAW account. Copy the code from the downloaded file and paste over all existing code in the file in your PAW account. In Python, indentation is important to code execution. If you have trouble running the program or you are getting errors when saving the file on PAW, check your indentation from copy/pasting. Be sure to hit the "Save" button once the code is pasted.
Do the same for your "CarriotsStatusBoard.py" file and "status.html" file. Again, be sure to hit the "Save" button each time.
You should now have updated a total of three files in your web app with new code. The web app isn't ready just yet. There needs to be some configuring.
Step 4: About Status.html
Perhaps the easiest file to understand is status.html. This file is essentially the mini-web page that is called by Status Board. This particular file though, is set up as a template in Flask. That means that data from our web application is populated into this template before it is served.
This particular file is built based on Panic's own "People In Space" example. In Status Board, a DIY Panel is basically a mini-web page that is specially formatted. Therefore our web page needs to be formatted properly. If you want to learn more, you can find the DIY Panel guide here. One great thing about this mini-web format is that it means you can also view this file in a browser if you aren't using Status Board. More on that later.
The special formatting is in the CSS of the web page. The CSS is built into the HTML file as opposed to calling a separate CSS file.
The other script functions set up an AJAX call that occurs every so often, in our case it is 60 seconds. This update call is to a special section of our application server that will return a JSON response instead of an HTML web page. That is, it returns only data. When the script receives a response, the data is parsed and the fields are updated so that the widget shows the most recent data.
Remember how I said you don't need an iPad to try out this widget? Here is why. The DIY Panel is really just a mini web page with some special formatting. That means just about any content could be displayed in Status Board. Or, for that matter, in a web browser. Now, part of the special formatting is a transparent background so that Status Board can render an appropriate background. A transparent background with white text usually won't look good in a standard browser, so a special parameter of "?desktop" can be added to the end of the URL to display the image in the browser. See the images in this step for an example.
On to the next file.
Step 5: About CarriortsStatusBoard.py
If you are familiar with Python or coding in general, you can probably find your way through these routines. The core element is that 'requests' is used to talk to the Carriots API to get device data. In order to do this, you will need to configure two parameters in this file.
Find the file in your PAW Dashboard and open it up for editing. Near the top of your file you should find app_key = 'YOUR_CARRIOTS_API_KEY_HERE'. This is the location to paste your API key, which is unique to you and your Carriots account. Keep this key protected. You can find the key by logging in to your Carriots account and selecting "My Settings" and then "My Account". You will see a field labeled "Apikey". Copy the 64 digits, all of them, and past it in between the single quotation marks in your CarriortsStatusBoard.py.
Next, find app_username = 'YOUR_CARRIOTS_ID_HERE'. This is the identifier that is used throughout the Carriots system for your account. For instance if you had a device test@Carriots, you would paste "Carriots" over the YOUR_CARRIOTS_ID_HERE. Be sure to keep the single quote marks. This is case sensitive, so be sure to copy your ID just as it is defined in Carriots. Your ID is the portion of the name after the @ sign.
Basically what each function is doing is making one or more requests to Carriots. The data that Carriots returns is put into a JSON structure and then certain fields are read in order to get the data that is to be served to our widget. You can learn more about Carriots API here.
This file is configured and ready to deploy. Be sure to save your updates.
Step 6: About Flask_app.py
This code defines two different "routes" or URLs that could be used. The first is /status/<device> and the second is /statusupdate/<device>. /status is used to serve the entire rendered web page - the HTML file. Notice how the return at the end of the function has render_template('status.html', device=device)? This is where our status.html template, that we created earlier, is integrated into the app.
/statusupdate/ is a route for responding only with data, not with an HTML file. When /statusupdate/ is called, it returns a JSON file. Notice the return jsonify statement at the end of the function. Basically the JSON file is a list of keys or names, and values.
Now, you probably took note of <device> in each URL name. This means that the URL takes a variable as part of it. In this case, it takes our device name. You will recall that we set up a device called myDevice. So, if we want to get the status of myDevice, we would call the URL /status/myDevice (case sensitive, be sure to use the proper case). When a browser or Status Board requests this URL, our Flask web app will parse off myDevice and use that to make the request to Carriots. Nifty trick, huh? It will keep you from having to write unique functions and web pages for each device you want to monitor. Instead, in the DIY Panel in Status Board, you just update the URL to point to the device you want to monitor.
You will notice that this file is using the functions in our CarriortsStatusBoard.py file.
OK - now you've got all the files updated and configured. You should have a general idea of how they work together too. Next up is deploying your web app.
Step 7: Launch the Web App!
Head over to your PythonAnywhere Dashboard. Click on the "Web" tab. Go ahead and press the big button labeled "Reload username.pythonanywhere.com". Obviously, username is replaced with your PAW username. You will get a spinner showing the web app is reloading. Anytime you make changes to one of the Python or HTML files we discussed, you will need to reload the web application.
Once the spinner has disappeared, try out your web application in your browser. You should be able to go to http://username.pythonanywhere.com/status/myDevice?desktop and see your widget in operation. Remember, replace username in the URL with your PAW username and if you used a different device name, replace myDevice with your actual device name. Be careful, the device name is case sensitive.
If you run into trouble in getting your widget to work, be sure to check the following.
1. That all code was copied in correctly, formatted and configured.
2. That you configured your Carriots API Key and Carriots ID properly.
3. That you reloaded your web application in PAW Web tab.
4. That you used the proper device name and case sensitivity.
If you need to, you can check your PAW server logs for any errors and chase those down.
Now - if you have never posted a data or status stream to this device, there won't be any important information to show in the widget. Let's post a quick data stream. Head over to your Carriots Control Panel. Under "Data Management" select "Wizard Send Streams". Work through the wizard. First select your device. Next create a key called "temperature", it could be anything though. For value use "23" or any value. Click "Next Step". Finally click "Send Stream".
Now, wait by your web browser with your widget displayed. Within a minute your widget should update to "Connected" status and show the time that the stream was posted. You could refresh your browser as well, though the page update still may take a few moments. Note that the time displayed on the page should be in the timezone of your browser and within the last minute or two, if you just posted a stream using the Carriots Wizard.
So you have a working web app, you have a working widget in the browser. Next, get it into Status Board.
Step 8: Configure Status Board With Your Widget and Warp Up.
Fire up Status Board on your iPad. Select the gear icon in the upper left corner. Drag a DIY Panel onto the board. The DIY Panel icon is the last icon on the right with the <> characters. Touch the new panel, and you will see a Do-It-Yourself dialog. In the Panel URL, paste or type in your URL used in the browser in the previous step, but without the ?desktop. So your URL may be http://username.pythonanywhere.com/status/myDevice.
YAY!!! You did it. You've now used Carriots, PythonAnywhere and Status Board to connect and display information. From this foundation you can build out other widgets such as graphing logged data.
Stay tuned for more tutorials on using Carriots, PythonAnywhere and Panic's Status Board. We look forward to hearing from you in the comments - let us know what you're creating.