From LEDs and APIs

by Patrick Stählin

As a programmer I’m not easily distracted if I’m really deep into a train of thoughts. Then again there are some events that need to be noticed, like a vendor issuing a notice about a scheduled downtime. I’m using Squirro to track those messages, but sometimes only get to read them the next day.

Recently I’ve participated in a Kickstarter campaign and backed the ThingM blink(1) project. It’s a little USB device that contains an LED. The LED can be controlled via software running on your PC. It’s shown in the photograph below. As the API of Squirro is open, I can check if my Squirro topic has unread items and turn the LED on or off depending on that.

Getting access

The API (and thus your data) is secured, so we need some kind of proof that we’re really the user we’re claiming to be. In Squirro we call this a ‘User token’. We’ve introduced this in December 2012 and generating it is as simple as pressing a button in Squirro. This link gets you to the settings page:

Now that we have the token, we can execute any action on the API in the context of the user. So it’s very important that you keep it to yourself. I’ve regenerated the token I’ve been using in this blog post, so it’s no longer valid.

All of our API calls require the tenant to be present in the request. Some requests also require the user-id. By now we only know the user token. But we can ask the User-API to get us this information:

packi@overlord:~$ curl -s https://user-api.squirro.com/oauth2/token 
                       -H 'Accept: application/json' 
                       -d grant_type=refresh_token    
                       -d refresh_token=3806c71b3bd520... | python -mjson.tool
{
    "access_token": "a23424ff...", 
    "refresh_token": "3806c71b3bd520...", 
    "session_id": "vxn32764S3CQf7OTxVZpkA", 
    "tenant": "linkedin-vmr1SvM-kp", 
    "user_id": "Pbo1MPruTpe5Mj3skX7rwQ"
}
packi@overlord:~$

Now we know that our user has the tenant linkedin-vmr1SvM-kp and the user ID Pbo1MPruTpe5Mj3skX7rwQ.

Getting the topic ID

The next thing we need to do is to is to retrieve the ID of the topic we’d like to watch. In my case it’s the topic called “Software and Vendors”. Looking at our documentation there is no call to search for a topic but there is one to retrieve all topics. Lets try that:

packi@overlord:~$ curl -s http://topic-api.squirro.com/v0/linkedin-vmr1SvM-kp/topics 
                       -H 'Accept: application/json' 
                       -u 3806c71b3bd520...: | python -mjson.tool
[
    [...]
    {
        "folder_id": "ArWO8TZQQNSJfddxpaaSHw", 
        "id": "APWIAjn5RJinSHjX4Q28uQ", 
        "is_ready": true, 
        "needs_preview": false, 
        "noise_level": 1.0, 
        "seeder": null, 
        "subscribed_to": true, 
        "title": "Software and Vendors", 
        "type": null, 
        "weight": 0.0
    },
    [...]
]
packi@overlord:~$

I had to shorten the output here but we’ve found the topic we were looking for. Please note the colon after the user-token. Without it cURL will ask you for a password.

Getting items

Now we can retrieve items for this topic. We’re only interested in unread items and just need to retrieve one of them to check if there are any. Passing

only_unread=true and count=1will do exactly that:

packi@overlord:~$ curl -s 'http://topic-api.squirro.com/v0/linkedin-vmr1SvM-kp/users/Pbo1MPruTpe5Mj3skX7rwQ/items?topics=APWIAjn5RJinSHjX4Q28uQ&only_unread=true&count=1' 
                       -H 'Accept: application/json' 
                       -u 3806c71b3bd520...: | python -mjson.tool
{
    "count": 1, 
    "eof": false, 
    "filtered": false, 
    "items": [
        {
            "title": "SubToMe Chrome Extension - ant0ine's blog",
            "id": "-BuQqGpHSLOAgzfIrlDOGw", 
            "link": "http://blog.ant0ine.com/typepad/2013/02/subtome-chrome-extension.html", 
            "read": false, 
            [...]
        }
    ]
}
packi@overlord:~$

What we’re getting back is one item It does match what I’m seeing on my Squirro account:

Analyze the return value

Since we’re only interested if there is in fact an item we can grep for the “count” field returned in the response:

packi@overlord:~$ curl -s 'http://topic-api.squirro.com/v0/linkedin-vmr1SvM-kp/users/Pbo1MPruTpe5Mj3skX7rwQ/items?topics=APWIAjn5RJinSHjX4Q28uQ&only_unread=true' -H 'Accept: application/json' -u 3806c71b3bd520...: | python -mjson.tool | grep '"count": 0'
packi@overlord:~$ echo $?
1
packi@overlord:~$ 

Turn on the light

Grep returns 1 if no made could be matched and we’re going to leverage this in a simple script to turn the LED on or off. The blink1 comes with various scripts to control it and it also has a command-line tool called blink1-tool. If it’s in your path you can turn the LED on and showing Red using:

blink1-tool --rgb 255,0,0

Turning it off is just as easy:

blink1-tool --rgb 0,0,0

So the script has to call these commands after checking the result of our topic query.

Putting things together

This is the script I’m running every 10 minutes. The LED of my blink(1) turns on whenever a new item arrives in my topic.

#!/bin/bash
TOPIC="APWIAjn5RJinSHjX4Q28uQ"
TENANT="linkedin-vmr1SvM-kp"
USER="Pbo1MPruTpe5Mj3skX7rwQ"
USER_TOKEN="3806c71b3bd520..."
curl -s "http://topic-api.squirro.com/v0/$TENANT/users/$USER/items?topics=$TOPIC&only_unread=true" 
     -H 'Accept: application/json' 
     -u $USER_TOKEN: | python -mjson.tool | grep '"count": 0'
RETVAL=$?
# if count is zero turn off the LED
[ $RETVAL -eq 0 ] && blink1-tool --rgb 0,0,0 2>&1 >/dev/null
# else turn it on
[ $RETVAL -ne 0 ] && blink1-tool --rgb 255,0,0 2>&1 >/dev/null

Seems like I have to catch up on some news items: