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 ...

>> 1
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
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
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
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.

Signup and Device Activation

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

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.

modelThe model number of the device
titleThe device title or name
descriptionA short description of the device
streamsAn 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.
controlsAn 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.
messagesAn 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.


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.

slugxThe name of the stream (space or underscore characters NOT allowed)
titlexA verbose title for the stream (must be set to "" if not used)
symbolxSymbol for the units. Symbols may be a text string e.g. kW or an HTML code, ° for example
unitxUnits for the stream, e.g. degrees C (must be set to "" if not used)
typeValid types are: boolean, integer, float. If type is not specified, float is assumed.


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.

slugxThe name of the control (space or underscore characters NOT allowed)
titlexA verbose title for the control (must be set to "" if not used)
symbolSymbol for the units. Symbols may be a text string e.g. kW or an HTML code, &deg for example.
unitUnits for the control, e.g. degrees C,
typexThe type of control. Available options are: boolean, integer, float, select
optionsIf type is select, a list of options that may be selected
valuexThe value to assign to the control
value_minMinimum value. Not valid for controls of type = select. value_min must be less than the value of value_max
value_maxMaximum value. Not valid for controls of type = select. value_max must be greater than the value of value_min


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.

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.

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.

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