Friday, January 27, 2017

Creating custom devices in Octoblu

Part 1: Use configuration events in Octoblu

This is something that I have been playing with for a very long time.
I directly use the Octoblu API to create my own devices.

I have copied existing devices, and I have created entirely new devices.
In this post I am going to create an entirely new device so that I can take advantage of the state (properties) feature to persist and evaluate data.

Why am I doing this instead of just reusing an existing Device?  Primarily because this makes a much easier to digest configuration change message on the listen side later on.  As there is a bare minimum number of properties.

Part 2 - Create a custom Octoblu device

Up front - I am a hard core Windows user (I do use Linux as well, but I have never used MAC) so my code example is in PowerShell.

Why would I create a custom device?
Well, my 'Thing' is an abstraction and not a physical device.

In practice, I have created 'rooms' in which I save data (aka set properties) from multiple sources or flows.  And I listen to specific data (property) changes of this device and then act on that data.

To do this there are a few things involved;
  • your security uuid and token
  • defining the security of the device
  • defining any custom properties of the device (if you want)
  • defining the base properties
  • performing the POST
  • looking at what you get back
Much of what is in the PowerShell below is all about building the object as a PowerShell object before it is converted to a JSON object.  Making sure that the data format is correct (arrays in the proper places, lists in the proper places, etc.)

# Octoblu User account (check your user properties)
$meAuthHeader = @{
    meshblu_auth_uuid = ''  
    meshblu_auth_token = ''
}


### build the JSON

# define the device permissions
$user = @()
$user += @{ uuid = $meAuthHeader.meshblu_auth_uuid }
$anyone = @()
$anyone += @{ uuid = '*' }
$empty = @()
$configureWhitelist = @{
    as = $empty;
    received = $empty;
    sent = $empty;
    update = $user
}
$message = @{
    as = $empty;
    received = $empty;
    sent = $anyone
}
$discover = @{
    as = $empty;
    view = $user
}
$broadcast = @{
    as = $empty;
    received = $anyone;
    sent = $anyone
}
$whitelists = @{
    configure = $configureWhitelist;
    message = $message;
    discover = $discover;
    broadcast = $broadcast
}

# define the schema of the device (behaviors and properties)

$properties = @{
    rooms = @{
        title = "sensors";
        type = "array";
        readonly = $true;
        items = @{
            type = "string"
        }
    }
}
$configure = @{
    Default = @{
        type = "object";
        properties = $properties;
        'x-form-schema' = @{
            angular = "configure.Default.angular"
        }
    }
}

$options = @{
    title = "Options";
    type = "object";
    properties = $properties
}
$configure = @{
    Default = @{
        title = "My Entity";
        type = "object";
        properties = @{
            options = $options
        };
        'x-form-schema' = @{
            angular = "configure.Default.angular"
        }
    }
}

$fields = @()
$fields += @{ key = "options.rooms" }
$form = @{
    configure = @{
        Default = @{
        angular = $fields
        }
    }
}

# wrap the above in the proper keys

$schemas = @{
    configure = $configure;
    form = $form;
    version = "2.0.0"
}

$meshblu = @{
    version = "2.0.0";
    whitelists = $whitelists;
}

# basic 'properties' (aka key:values) of the Device

$body = @{
    online = $true;
    owner = $meAuthHeader.meshblu_auth_uuid;
    type = "device:myDeviceType";
    name = "myDeviceName";
    city = "Redmond";
    meshblu = $meshblu;
    schemas = $schemas
}

# convert the PowerShell object to a JSON object

$json_body = $body | ConvertTo-Json -Depth 99

### create the device

$device = Invoke-RestMethod -URI http://meshblu-http.octoblu.com/devices -ContentType "application/json" -body $json_body -Method Post

$device | ConvertTo-Json -Depth 99


Now record the uuid and token of your device.  This is the ONLY time you get this token back, and you would need to generate a new one to know it again.

Also, you can set other properties such as a 'logo'.  For the logo the value must be an HTTPS URL reference to an SVG.

Next up:  Setting properties from a flow to this device.

No comments: