goHACK.me

The goHACK.me API provided by WiConnect enables monitoring and control of your ACKme device. You can set up a goHACK.me account, then using goHACK.me commands and goHACK.me variables, you can activate your device and synchronize data, control and messages with the goHACK.me cloud service.

NOTE! WiConnect version 1.2 or higher is required to use goHACK.me. To update WiConnect, use the OTA update command.

Getting Started with goHACK.me

Eager to get started? No problem! Let's jump right in and get your new device connected (we'll get to the details of how goHACK.me works later).

The goHACK.me promise: Connect your device ready for control from the internet in just a few easy steps ...

Step	Description
>> 1 Signup	The first step to getting started with goHACK.me is to signup for an account. Go to the goHACK.me site and click the SIGNUP button to create your account.
>> 2 Connect	Plug your Mackerel (or other ACKme device) into your computer via USB and open a WiConnect terminal (see Getting Started), then enter the network_up command at the prompt as shown below. The device scans for Wi-Fi networks in range, and offers a selection of available networks. Pick your network and enter the network password.

> network_up -s

>> 3
Setup

When a device activates with goHACK.me, it tells goHACK.me what it can do (or is capable of doing) by sending a capabilities file. To get you started, ACKme provides an example capabilities file that is perfectly suited to your device. And even better, we also provide an example automated configuration script to set up your device to go SOLO. No external host micro needed!

To download and setup your device with example default capabilities, enter the ghm_capabilities command at the prompt as shown below.
\

> ghm_capabilities download -s

>> 4
Activation

Activate the device with goHACK.me using the ghm_activate command. This will associate the device with your account.
A valid goHACK.me username and password must be provided.
\

ghm_activate youremail@address.com yourpassword

Congratulations! Your device is now connected, setup and ready for use with your shiny new goHACK.me account.

To see your device on goHACK.me, open a web browser and login to goHACK.me. After login, your device appears in the goHACK.me device view. Assuming your device has one or more LED lights on it (and all of our devices do) go ahead and press a button and within a few seconds, the corresponding LED on your device will magically turn on!

Using WiConnect with goHACK.me

The following sections provide a brief overview of how to use WiConnect with goHACK.me. We suggest you review the goHACK.me Getting Started Guide to familiarize yourself with goHACK.me before continuing.

Slave vs. Solo Mode

WiConnect can be used in one of two modes with goHACK.me. Read on and decide which mode works best for your connected application.

Slave mode. In slave mode, WiConnect is a slave to a host microcontroller (or computer). The MCU communicates with goHACK.me using commands built into WiConnect. For example, the host may sync streams and controls with goHACK.me by using the ghm_sync command.
Solo mode. In solo mode, WiConnect operates standalone (no host MCU needed) and automatically syncs with the goHACK.me cloud. Solo mode is enabled by setting the WiConnect ghm.solo.enabled variable, and GPIOs used with solo mode are configured with ghm.solo.gpio. The solo mode sync period i.e. how often stream samples are sent to goHACK.me, is configured using ghm.solo.sync_period.

Create a goHACK.me user account and activate your device with goHACK.me as described in Getting Started above.

If you already have a goHACK.me account, use the ghm_activate command to activate additional devices as shown in the following example.

Note: The ghm_activate command attempts to read the device capabilities file configured with the WiConnect ghm_capabilities command. To check whether your device is already activated, read the ghm.status variable.

> ghm_activate your-email@address.com ********
Request POST /api/activate/login
Connecting (HTTPS): api.gohack.me:443
Starting TLS
HTTP response: 200
Success

Device Capabilities

When your device is activated using the ghm_activate command, the device tells goHACK.me what it is capable of doing. Device capabilities (stored as a file in JSON format), describe device functionality, preferences, messages and information about connected I/O including the number of I/Os connected, a name for each I/O, a type or range for each I/O, plus more ... In WiConnect & goHACK.me documentation, capabilities file is referred to simply as the "caps" file.

A caps file has the following entries.

Entry	Description
`model`	The model number of the device
`title`	The device title or name
`description`	A short description of the device
`streams`	An array of (read-only) sampled streams sent to goHACK.me. Examples include the open/close state of a door, the temperature of your wine cellar, etc.
`controls`	An array of (read/write) control parameters. Control parameters may be changed on goHACK.me and are read by the device. Since controls are used to control physical "things" connected to your device, your porch light for example, controls are also writeable by the device. This enables you to bypass goHACK.me to control your porch light directly from the device if required.
`messages`	An array of message boxes that enable messages to be sent to, and received from, your device

The goHACK.me ghm_activate command reads the caps file (configured using the ghm_capabilities command) from the file system.

Streams

goHACK.me devices send streams of data samples to the goHACK.me server. Each stream carries samples of the state or value of an I/O connected to the device. Streams enable you to monitor and measure your "things". Some example streams include the temperature of your wine cellar, the open/close state of the back door, or the amount of energy the pool pump is using.

The caps file contains an array of streams to monitor "things" connected to your device. Each stream in the caps file contains the following entries.

Entry	Mandatory	Description
`slug`	x	The name of the stream (space or underscore characters NOT allowed)
`title`	x	A verbose title for the stream (must be set to "" if not used)
`symbol`	x	Symbol for the units. Symbols may be a text string e.g. `kW` or an HTML code, `°` for example
`unit`	x	Units for the stream, e.g. degrees C (must be set to "" if not used)
`type`		Valid types are: `boolean`, `integer`, `float`. If `type` is not specified, `float` is assumed.

Controls

Control parameters allow you to send commands to your device to in turn control "things" connected to it. Some examples include turn on the porch light, open the garage door or set the heat to 75 degrees.

The caps file contains an array of controls to control "things" connected to your device. Each control in the caps file contains the following entries.

Entry	Mandatory	Description
`slug`	x	The name of the control (space or underscore characters NOT allowed)
`title`	x	A verbose title for the control (must be set to "" if not used)
`symbol`		Symbol for the units. Symbols may be a text string e.g. `kW` or an HTML code, `&deg` for example.
`unit`		Units for the control, e.g. degrees C,
`type`	x	The type of control. Available options are: `boolean`, `integer`, `float`, `select`
`options`		If `type` is `select`, a list of `options` that may be selected
`value`	x	The value to assign to the control
`value_min`		Minimum value. Not valid for controls of `type` = `select`. `value_min` must be less than the value of `value_max`
`value_max`		Maximum value. Not valid for controls of `type` = `select`. `value_max` must be greater than the value of `value_min`

Messages

goHACK.me provides the capability to send messages to your devices and to receive messages from your devices. Messages are currently limited to plain text, however goHACK.me will support a range of message types including audio clips and images in the future.

To enable messaging to and from your device, the caps file must contain a messages section. The messages section is not configurable, and must appear in the caps file exactly as shown in the following example capabilities object. Message box titles may be changed to suit your requirements.

Example Caps File

The following text provides an example caps file for the Mackerel board v3, together with a description of how to write the caps file to the WiConnect file system, and set the caps file for use with goHACK.me.

{
    "model": "AMW004-E03.3",
    "title": "Mackerel",
    "streams": [
        {
            "slug": "button1",
            "title": "Button 1",
            "unit": "On/Off",
            "symbol": "",
            "type": "boolean"
        },
        {
            "slug": "button2",
            "title": "Button 2",
            "unit": "On/Off",
            "symbol": "",
            "type": "boolean"
        },
        {
            "slug": "thermistor",
            "title": "Thermistor",
            "unit": "Levels",
            "symbol": "",
            "type": "integer"
        }
    ],
    "controls": [
        {
            "slug": "led1",
            "title": "LED 1",
            "value": 0,
            "type": "boolean"
        },
        {
            "slug": "led2-duty",
            "title": "LED 2 PWM Duty Cycle",
            "value": 20,
            "value_min": 0,
            "value_max": 100,
            "type": "integer"
        },
        {
            "slug": "led2-freq",
            "title": "LED 2 PWM Frequency",
            "value": 1000,
            "type": "integer",
            "value_min": 1,
            "value_max": 1200000
        }
    ],
    "messages": [
        {
            "slug": "from-device",
            "title": "From Device"
        },
        {
            "slug": "to-device",
            "title": "To Device"
        }
    ]
}

To write the caps file (shown above) to the WiConnect file system and configure the caps file for use with goHACKme, use the WiConnect file_create commands as follows.

> file_create ghm_capabilities.json 1445
 ... paste caps text here ...
> ghm_capabilities set ghm_capabilities.json

NOTE: Some terminal applications may incorrectly translate EOL characters, if you're having trouble with the above example, try the following caps file with all non-essential whitespace removed. The length of the caps file must be changed to match the reduced number of characters in the file.

If you are having trouble cutting and pasting the above capabilities object with whitespace included, try using the following version which has all whitespace removed. For reference, a useful Windows editor for removing non-essential whitespace is Notepad++.

{ "model": "AMW004-E03.3", "title": "Mackerel", "streams": [ { "slug": "button1", "title": "Button 1", "unit": "On/Off", "symbol": "", "type": "boolean" }, { "slug": "button2", "title": "Button 2", "unit": "On/Off", "symbol": "", "type": "boolean" }, { "slug": "thermistor", "title": "Thermistor", "unit": "Levels", "symbol": "", "type": "integer" } ], "controls": [ { "slug": "led1", "title": "LED 1", "value": 0, "type": "boolean" }, { "slug": "led2-duty", "title": "LED 2 PWM Duty Cycle", "value": 20, "value_min": 0, "value_max": 100, "type": "integer" }, { "slug": "led2-freq", "title": "LED 2 PWM Frequency", "value": 1000, "type": "integer", "value_min": 1, "value_max": 1200000 } ], "messages": [ { "slug": "from-device", "title": "From Device" }, { "slug": "to-device", "title": "To Device" } ] }

And here's the corresponding file_create and ghm.capabilities set commands (with a reduced character count to match the lack of whitespace) for completeness ...

> file_create ghm_capabilities.json 805
> set ghm.capabilities ghm_capabilities.json

The goHACK.me API

A common set of WiConnect goHACK.me API commands and variables are used for device activation/deactivation and basic setup, whether the device is used in slave mode or solo mode. These commands/variables are summarized in the following list.

Commands
- ghm_activate -- Activate additional devices with goHACK.me
- ghm_capabilities -- Setup device capabilities
- ghm_deactivate -- Deactivate a device
Variables
- ghm.cache_size -- Set the local stream cache size
- ghm.capabilities -- Read the caps filename
- ghm.status -- Read the device activation status

Slave Mode

In slave mode, the host writes streams and controls using ghm_write, and reads controls (from a local cache after a sync) using ghm_read. To manually force stream samples to be pushed to goHACK.me, and the latest control values to be pulled from goHACK.me, the host uses the ghm_sync command. Messages may be sent or received using ghm_message and read or written using the stream_read, stream_write and stream_close commands.

When stream samples are written, a local cache is provided to minimize the overhead and additional power drain of connecting to the network to send individual samples. The number of samples cached before automatically pushing to goHACK.me is configurable with the ghm.cache_size variable. To immediately push all locally cached samples to goHACK.me, use the ghm.sync command with the push option. A summary of commands used with slave mode is provided in the following list.

ghm_message -- Send & receive messages
ghm_read -- Read controls
ghm_sync -- Synchronize streams and controls with goHACK.me
ghm_write -- Write streams and controls

Solo Mode

In solo mode, streams are automatically synchronized with goHACK.me. Solo mode is enabled by setting the WiConnect ghm.solo.enabled variable, and GPIOs used with solo mode are configured with ghm.solo.gpio. The synchronization period is configured with ghm.solo.sync_period. After synchronization, any changes in control parameters are printed to the WiConnect bus.log_bus if ghm.solo.echo is enabled.

ghm.solo.echo -- Echo changes to controls to the bus.log_bus
ghm.solo.enabled -- Enable/disable solo mode
ghm.solo.gpio -- Configure GPIOs connected to streams/controls
ghm.solo.sync_period -- Configure the period to sync with goHACK.me

In solo mode, WiConnect operates standalone (no host MCU needed) and automatically syncs with the goHACK.me cloud. The solo mode sync period i.e. how often stream samples are sent to goHACK.me, is configured using ghm.solo.sync_period.

goHACK.me Basic Account

A basic goHACK.me account is provided entirely free for use by customers of ACKme Networks. The basic account is provided with some limitations as outlined in the following list. If you need an unrestricted commercial cloud service, please contact ACKme at http://ack.me/contact

Devices are limited to a maximum of 4 samples and 4 controls
The minimum period for synchronisation with goHACK.me is 4 seconds
Each account is limited to a maximum of 4 devices
Accounts are limited to a maximum of 4 triggers