command-and-control-service

Table of Contents

• Introduction
• Getting Started
• Usage
  • Install
  • Default
  • Docker
    • Development
    • Production
  • Debugging
  • Test
• License

Introduction

The command and control service allows rules to be applied to messages or configuration changes on a Meshblu device and perform updates on another.

Getting Started

1. Create a Rule file
2. Create Ruleset device
3. Add webhook and properties

Create a Rule file

The meshblu-rules-engine is based on processing rules from the JSON Rules Engine.

Meshblu-rules-engine processes rules in the basic format of:

{
  "if": {...rules...},
  "else": {...rules...}
}

where the "else" block is processed only if no conditions are true in the "if" block.

See an example in smartspaces-core-rules.

Events should be in format:

{
  "type": "meshblu",
  "params": {
    "operation": "message",
    "as": optional,
    "message": {
      "devices": [ ... ],
      ...
    }
  }
}

or

{
  "type": "meshblu",
  "params": {
    "operation": "update",
    "as": optional,
    "uuid": required,
    "data": {
      ...
    }
  }
}  

Create Ruleset Device

Using the command and control system requires a new Meshblu device called the Ruleset. The Ruleset is a device that contains a list of URLs that point to the various rules that will be applied.

Example Ruleset Device

{
  "name": "Ruleset",
  "type": "meshblu:ruleset",
  "rules": [
    {
      "url": "https://raw.githubusercontent.com/octoblu/smartspaces-core-rules/master/hue-button-start-meeting-or-skype/action.json"
    }
  ]
}

Add Webhook and properties

On the device that will have the rules applied to it, you will need to set up a webhook to forward events to the command and control service.

Example Webhook

{
  "name": "My Device",
  "meshblu": {
    "forwarders": {
      "version": "2.0.0",
      "broadcast": {
        "sent": [
          {
            "type": "webhook",
            "url": "https://command-and-control.octoblu.com/v1/messages",
            "method": "POST",
            "generateAndForwardMeshbluCredentials": true
          }
        ]
      },
      "configure": {
        "sent": [
          {
            "type": "webhook",
            "url": "https://command-and-control.octoblu.com/v1/messages",
            "method": "POST",
            "generateAndForwardMeshbluCredentials": true
          }
        ]
      }
    }
  }
}

The webhooked device should also be configured with a "commandAndControl.rulesets" property to point to the newly created Ruleset device:

{
  "commandAndControl": {
    "rulesets": [
      {
        "uuid": rule-set-device-uuuid
      }
    ],
    "errorDevice": {
      "uuid": "error-device-uuid",
      "logLevel": "error"
    }
  }
}

An optional "errorDevice" property will forward errors from the command-and-control-service to the error device. The property logLevel can be one of error/info, and defaults to error. When set to error, the device will only be notified about rule enforcements that resulted in an error. When set to info, all rule enforcements will be sent to the device.

Note: Previously, there was an errorDeviceId property that could be used to register a device for update notifications. This property has been deprecated, and was removed on March 1st 2017.

Install

git clone https://github.com/octoblu/command-and-control-service.git
cd /path/to/command-and-control-service
npm install

Default

node command.js

Docker

Development

docker build -t local/command-and-control-service .
docker run --rm -it --name command-and-control-service-local -p 8888:80 local/command-and-control-service

Production

docker pull quay.io/octoblu/command-and-control-service
docker run --rm -p 8888:80 quay.io/octoblu/command-and-control-service

Debugging

env DEBUG='command-and-control-service*' node command.js

env DEBUG='command-and-control-service*' node command.js

Test

npm test

License

The MIT License (MIT)

Copyright (c) 2016 Octoblu

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.