Friday, April 10, 2015

Giving of your Octoblu devices

I realize that the title is not very searchable, and I am okay with that.

After all, this post is all about giving.  Actually moving ( handing over, granting, getting rid of ) a device on the Octoblu IoT platform.

To stay true to my Windows roots, I did this in PowerShell  ;-)

Here is my scenario, I have been working with a 'device' in Octoblu.  I have it all setup, it is working well, there is a flow tied to it, etc.  The world is a happy place.

Now, I am done with this.  But Joe wants to carry it on and take it to a show and demonstrate it, possibly even enhance the flow.
I developed the entire thing under my account, and I can't give Joe my password.

I could use the template feature and give Joe a device scrubbed version of my flow.  But that still requires that the device be deleted from my account and re-created under Joe's.  Or Joe has to take the device, reconfigure it and then personalize the flow.

Why not just give Joe my device - and I mean really give it.  Not just the physical device, but its representation on the platform and the flow that goes along with it.

To accomplish this I only have to do a few things:  I have to add Joe's user account to the device, then Joe needs to claim (take ownership) of that device.

In Octoblu everything is a 'device'; users, things, flows, running flows, etc.  A user is just a special type of device.

Octoblu also has a whitelist / blacklist security model that grants or denies access at the very granular device level.  You can literally have a device that can only talk to one other device (such as the flow it interacts with) and nothing else. 

By default, this is all locked down and your devices are only available to you and to the flows to link them to in the designer.

At the same time, there is no way to 'give this to Joe'.

Let me get to the meat and walk through a few things.

First of all, we will do all of this through the REST API.  And the REST API uses your user UUID and secret (they call a token) to authenticate you.

Using this you can authenticate and list your devices.
And get the UUID of the device (or UUIDs of devices) that you want to give.

The next piece of information you need is the UUID of the user you want to give the device to.

The rest is in the script (with some error handling of course).
You can find the source over here: https://github.com/brianehlert/moveOctobluDevice

And you can find the first version below:

# What is the UUID and token of the current device owner?
# and test that it is actually good
Do {
    Do {
        if (!$deviceOwner) { $deviceOwner = Read-Host -Prompt "What is the uuid of the current device owner? (your account)" }
        if (!$deviceOwnerSecret) { $deviceOwnerSecret = Read-Host -Prompt "What is the secret token of the current device owner? (your account)" }
        $meAuthHeader = @{
            meshblu_auth_uuid = $deviceOwner  
            meshblu_auth_token = $deviceOwnerSecret
        }
        $me = Invoke-RestMethod -URI ("http://meshblu.octoblu.com/devices/" + $deviceOwner) -Headers $meAuthHeader -Method Get -ErrorAction SilentlyContinue
    } Until ( $me )
    # echo back what you find
    "The current device owner is: " + $me.devices[0].octoblu.email
} until ( (Read-Host -Prompt "Is this correct? Type 'YES'") -eq 'YES' )

# What is the UUID of the user you will be moving your devices to?
# and test that it is actually good.
Do {
    Do {
        if (!$deviceNewOwner) { $deviceNewOwner = Read-Host -Prompt "What is the uuid of the new device owner? " }
        if (!$deviceNewOwnerSecret) { $deviceNewOwnerSecret = Read-Host -Prompt "What is the secret token of the new device owner? " }
        $youAuthHeader = @{
            meshblu_auth_uuid = $deviceNewOwner  
            meshblu_auth_token = $deviceNewOwnerSecret
        }
        If ($deviceNewOwnerSecret) {
            $you = Invoke-RestMethod -URI ("http://meshblu.octoblu.com/devices/" + $deviceNewOwner) -Headers $youAuthHeader -Method Get -ErrorAction SilentlyContinue
        } else { $you.devices.octoblu.email = "No token provided. Unable to validate" }
    } until ($you)
   
    # echo back what you find
    "The new device owner will be: " + $you.devices[0].octoblu.email
} until ( (Read-Host -Prompt "Is this the correct new device owner? Type 'YES'") -eq 'YES' )

# List all of 'my devices' in a nice, neat way with the important bits - name, uuid, device type
$devices = Invoke-RestMethod -URI http://meshblu.octoblu.com/mydevices -Headers $meAuthHeader -Method Get
# Which device will you be moving to another user?
# base on device name as everything associated in the case of Gateblu needs to go.
Do {
    $devices.devices | Sort-Object Name | Format-Table -AutoSize name, uuid, type, subtype, online

    Do {
        if (!$nameToMove) { $nameToMove = Read-Host -Prompt "What is the name of the device you will be moving to the other user? (this is a match)" }
        $deviceToMove = $devices.devices -match $nameToMove }
    Until ( $deviceToMove )
    "The following device(s) matched: "
    $deviceToMove | Format-Table -AutoSize Name, UUID
} until ( (Read-Host -Prompt "proceed to move your device(s)? Type 'YES'") -eq 'YES' )
# The device only needs to be discoverable to take ownership.
foreach ( $device in $deviceToMove ) {
   
    If ( $device.discoverWhitelist ) {
        $device.discoverWhitelist += $deviceNewOwner
        $json = @{
            "discoverWhitelist" = $device.discoverWhitelist
        }
    } else {
        $json = @{
            "discoverWhitelist" = $deviceNewOwner
        }
    }
    $json = $json | ConvertTo-Json
    # make the device discoverable by the new owner
    Invoke-RestMethod -URI ( "http://meshblu.octoblu.com/devices/" + $device.uuid ) -ContentType "application/json" -Body $json -Headers $meAuthHeader -Method Put
    If ( $youAuthHeader.meshblu_auth_token ) {
        # claim the device as the new owner
        # only if you know the token - otherwise the other user will need to do that
        Invoke-RestMethod -URI ("http://meshblu.octoblu.com/claimdevice/" + $device.uuid ) -ContentType "application/json" -Headers $youAuthHeader -Method Put
    }
}

No comments: