User Modules

User Modules are a way for you to create and deploy your own custom services to your Canaries. Once deployed, your Canary will listen on the specified port, and once hit, will behave in the way you want it to.

Creating your custom service is quick and can be easily done by following the below steps.

Steps

1

Setup environment

Setup and activate python virtual environment:

/Users/canary/Work/usermodules/

  • virtualenv usermodenv
  • source usermodenv/bin/activate

Install canaryusermodule python module

/Users/canary/Work/usermodules/

  • pip install canaryusermodule

2

Generate test module and install into virtual env

Generate test module:

/Users/canary/Work/usermodules/

  • usermodgen HelloTest

Install test module into virtual env:

/Users/canary/Work/usermodules/

  • cd hellotest
  • python setup.py develop

3

Dev and test module

Test with and watch raw json logs in foreground:

/Users/canary/Work/usermodules/hellotest/

  • opencanaryd --usermodule

hack, hack, hack

Repeat above as desired.

4

Optional: delete test user module from virtual enviroment

Delete test module from virtual env:

/Users/canary/Work/usermodules/hellotest/

  • pip uninstall -y hellotest

5

Build and upload

Build test module:

/Users/canary/Work/usermodules/hellotest/

  • ./build.sh

The usermodule will be the *.whl in dist. Upload this to canary.

/Users/canary/Work/usermodules/hellotest/

  • ./dist/HelloTest-1.0-py2-none-any.whl

More information

In order to upload your user module you will need to boot your device into configuration mode.

Your Canary can only be configured when its in "config" mode (otherwise it could be reconfigured when running, which is bad mmmkay.) The very first boot automatically enters config mode, and once configured the device defaults to live mode whenever it's powered on.

To re-enter config mode, disconnect the power supply, press the small button next to the Ethernet port and connect the power. Reset Button Hold the button in until the status LED shows purple. After a short while, the LED will go blue, at which point the config interface on http://setup.canary.tools is accessible again.

If you're successfully connected to the Bluetooth network, then this error means that your browser doesn't also have an Internet connection. This isn't a train smash, you can still browse to the configuration site over Bluetooth using http://10.9.8.7.

If your Bluetooth network is not connected, ensure that your OS is setup to support Bluetooth network connections. For example, on Mac OS you might have to first add a "Bluetooth PAN" interface in your Network Preferences.

In the event that you cannot connect to Bluetooth and your Ethernet network supports DHCP, your Canary will advertise its Ethernet IP in its Bluetooth name. You can browse to this IP from a machine on the same Ethernet network.

In some cases, the Canary's automatic registration can fail. Typically this occurs when the user configuring the Canary is not also logged into their hosted console, perhaps because the user does not have external web access at that time.

Canaries support an offline or manual registration flow too. This process requires you to copy data from the Canary's config interface to the hosted console, and vice versa. Here are the steps:

  • After trying the Canary's automatic registration, you see this error:
  • Copy the blob of data from the textfield:
  • Log in to your hosted console, and click Setup:
  • Then click Commission a new Canary to bring up the new device modal:
  • Paste the blob copied from the Canary into the text area:
  • Click Import. This will register the Canary with your console.
  • The second part of the process is to register the console with the Canary. Copy the data blob shown in the hosted console to your clipboard:
  • Then switch back to your Canary's config screen and paste the console blob into the text field and click Submit:
  • A successful import on the Canary shows this message, click Finish to reboot into production mode:
  • On your hosted Console, click Take me to Approval:
  • Finally, approve your new Canary to complete the registration:
  • Your Canary is now registered, you can unplug it and move it to its production location.

The status LED provides feedback about the Canary's current state, using colour and flashing.

Off
Canary software has not run, power is likely off.
Purple
Booting into config mode.
Blue
Config mode is running.
Orange
Booting into live mode.
Green
Canary is running in live mode, in contact with the server.
Red
Canary is running in live mode, but cannot contact the server.
Flashing Red
Canary software has exited. Reboot your Canary.