Updated June 4: I’ve corrected a couple of things, as marked in blue. Also, developers might be interested in my follow-up blog entry A Nimbits Gadget: Programmer’s Show And Tell
Updated Dec 3/11: I fixed a broken feature: autoscaling of the Y axis was no longer working, resulting in values above 100 being cut-off.
Updated Dec 14/11: I’ve added a couple of new settings: Graph Width and Gadget Height. For details, see the “Settings” section below.
As mentioned in my post about the data-logging service Pachube, I found the best way to monitor my datastreams was with the Pachube Google Gadget. Stick it on your iGoogle page, and it allows you to quickly and conveniently keep an eye on your data without having to go out of your way to find it.
When I started logging data to the open source Nimbits system, the first thing I went looking for was some equally convenient way to keep tabs on my Nimbits data. While Nimbits offers a lot of built-in methods for monitoring your data, such as e-mail, Google Talk, and Twitter, I decided that nothing worked as well for me as that Gadget. So, I decided to write a Nimbits Gadget.
The Gadget displays up to 3 line graphs, with each line graph containing as many Data Points (i.e. datastreams) as you like. You can optionally include a Status line showing the last data point received.
You can grab the gadget from its Google Directory page.
In this post I’ll describe the settings for the Gadget, and in the next post I’ll write a bit about the Gadget code and the underlying Nimbits API.
What You’ll Need
If you’ve never used Nimbits before, you’ll need to start posting data to it before the Gadget will do you any good. The Gadget is display-only – it won’t help you get data into the system. The process of creating and configuring a Nimbits account and adding Data Points to it was described in an earlier post.
One major caveat: the Data Points that the Gadget displays must be Public. Admittedly, this is just to keep the coding relatively simple. Private data points require authentication, something which can be tricky from a Javascript application like a Gadget, though I expect (hope?) that this will be streamlined somewhat by the shared Googly underpinnings of Nimbits and the gadget. If it works, I’ll add authentication in a future update of the code.
Settings
The settings dialog, shown below, is longer than the average gadget’s. Not to brag, or anything.
Most of the options are there so that you can tinker with the gadget appearance and features to see what suits you best. The defaults should work fine, but there are a few settings which you’ll need to supply. Let’s start with those.
Required Settings
Server
If you are using the public Nimbits server, then leave this at the default, app.nimbits.com. If you’ve installed your own copy of the Nimbits code on the Google App Engine, then fill in the name of that GAE instance (usually your-app-name.appspot.com)
Data Points
In Nimbits, a Data Point is the unique name assigned to a specific datastream. For example, in the screenshot to the right there are 2 Data Points, Home Meter and Plant Light. (Power Usage is a category – the Gadget only works with Data Points, not Categories).
Enter the name of a Data Point in the textbox then click the Add button. You’ll then see it listed below the textbox.
To add a second Data Point to the same graph, enter its name in the textbox then click the Add button. (You have to add them one at a time, rather than typing them in all at once).
To display a Data Point in a separate graph, click the “Display Graph 2?” checkbox to turn it on. Fill in the name of the Data Point in its textbox then click the Add button.
The following screenshot shows 2 Data Points added to the 1st graph, and 1 Data Point in the second graph.
To remove a Data Point from a graph, click the “X” next to the Data Point name. To remove a graph entirely, turn off its checkbox. (OK, here’s the thing: You can’t remove a graph by removing all of its Data Points – Google’s idea, not mine. The gadget “list” interface pretends to remove them, then adds back the last item when you’re not looking. Apparently, that is not evil.)
Your Email Address
This field is mandatory when using the public Nimbits server (i.e. when the Server fields is app.nimbits.com). That’s how Nimbits figures out which Data Points belong to you.
The field is optional if you’ve setup your own Nimbits server using the Google App Engine.
Update June 4: Actually, the e-mail address is optional when using your own Nimbits server only if you’re authenticated with the backend Google App Engine. Since I’m not sure what triggers that authentication, you should just go ahead and fill in your e-mail address.
Graph Height
This determine the height, in pixels, of the graph. The default of 200 will only allow one full graph to fit. A size of 80 will allow 2 graphs with Status lines to fit.
Graph Width [Added: Dec 14 2011]
This determines the width, in pixels, of each graph. The default of 310 pixels fits snugly in the gadget container on my desktop PC, but the optimal width will vary depending on the browser and device you’re using.
Gadget Height [Added: Dec 14 2011]
This determines the height, in pixels, of the gadget container. The default setting is 240 pixels, which is big enough for a couple of graphs and status lines.
Other Settings
Time Span
The amount of data displayed on the graph is specified in the Time Span field. You can enter it either as hour or as # of readings. In either case, you’ll get the most recent data: that is, the most recent x hours of data, or the most recent x readings.
By default, this is set to display the last 24 hours of data.
Legend
This option determines whether a list of the Data Points and their colours are displayed at the top of the graph. This option is particularly useful if you have multiple Data Points in a graph. Turning the legend off frees up more vertical space for the data in the graph.
Grid Style
This option determines the grid lines displayed on the graph: None, Vertical, Horizontal or Both. You can have any number of grid lines you like, as long as that number is 10.
Show Status
This option determines whether a status line is displayed above each graph, giving the name of the first Data Point and the date and time of the last reading. The status is particularly useful to identify that your data stream has stopped working, since the line graph won’t make that outage apparent. (Integrating downtime into the graph is definitely a top priority for future updates of the gadget.)
The downside to displaying the status is that it slows down the refresh time of the gadget, and (ahem) the code doesn’t always work. See the Troubleshooting section below if the Status line displays something other than a status.
Troubleshooting
Blank or missing graphs
When something goes wrong, you generally end up with a blank graph rather than an error message. That’s kind of by design: if there is no data matching the settings, the Nimbits API will dutifully provide an empty set of data to Google Charts, which will dutifully display it.
If the graphs are missing entirely, then the gadget likely couldn’t find a Nimbits server, so check your Server setting.
If blank graphs are displayed, try turning on the Legend and Status options in the settings – they may give an indication of what went wrong.
If the legend is labeled “Doesn’t exist”, then the Data Point might not have been correctly entered in the settings.
Status line errors
The Status might be set to one of the following errors:
- The requested URL /service/currentvalue was not found on this server. Check the server name in the settings. This error means the server exists, but Nimbits isn’t running on it.
- Could not identify user. Check the email address field in the settings.
- Status unknown or Undefined. Unfortunately, there seem to be a variety of causes to this one. The problem isn’t with the settings – it’s likely something I can fix in the code. So, don’t blame yourself, blame me. Fixing this is a priority for future versions of the gadget.
Slow updates
If the Gadget takes too long to update itself, try turning off the Status option in the settings, and/or putting multiple Data Points on the same graph. Each graph and each status field require an extra call to the Nimbits server. Three data points on one graph take much less time to appear than 3 graphs.
Data isn’t updated often enough
Chill, dude! Updates to the graphs and status will only appear every 5 minutes, no matter how much you click the browser Refresh button. This is by design. Google caches the data used by the gadgets, and I’ve set the cache length for 5 minutes.
If you don’t manually refresh the browser page, iGoogle will update all of the gadgets just once per hour.
Some graphs don’t fit
I left the Gadget height at its default, and there is no way for the user to increase the size of a gadget in iGoogle. You can fit more graphs in the space by reducing the Graph Height in the Settings dialog. The default of 200 will fit just one graph; a Graph Height of 80 should fit two graphs with their status fields.
You can see an expanded view of all graphs by clicking Maximize control button on the titlebar, or by selecting the Nimbits gadget in the list on the left of the iGoogle screen.
Wrapping Up
If you have any problems, or requests for features in future versions of the gadget, please leave a comment below.