NAV Navbar
Logo
json javascript

Introduction API v0.0.3

This is the Metasploit Hardware Bridge API. The Hardware bridge enables metasploit to interact with physical hardware in an effort to perform security testing on non-ethernet based systems. The focus of this documentation may seem backwards compared to other API documents. Unlike most API documentation that teaches you how to interact with the server, this document teaches you how to build in API support into your hardware. In effect, guiding you on how to create your own small embedded system that is Metasploit compatible.

We will try to include language bindings for different embedded system languages as well as ruby. Ruby is used mainly as a general example and you can view a simple implementation by looking at the Metasploit module: auxiliary/server/local_hwbridge.

This API documentation page was created with Slate.

Server Setup

You can setup your web server any way you want. You can write your own REST like client or use a library. We will include some examples here using some common libraries. For Node.js we will assume the use of the Express library. Use the ‘javascript’ tab in the top right to view javascript/nodejs samples.

Installing the Express library with nodejs

npm init
npm install express --save

Initialize the express REST server as app

var http = require('http');
var express = require('express');

var app = express();

Ports & URI

// This should come after all of your app routes
app.listen(8080);

There is not a standard for what port your device needs to listen to. The URI to connect can be the root ’/’ or anything else. The auxiliary/client/hwbridge/connect module support a TARGETURI option that can be used to connect to any URI that is needed for the root of your API server.

Encryption

var fs = require('fs');
var http = require('http');
var https = require('https');
var privateKey  = fs.readFileSync('sslcert/server.key', 'utf8');
var certificate = fs.readFileSync('sslcert/server.crt', 'utf8');

var credentials = {key: privateKey, cert: certificate};
var express = require('express');
var app = express();

// express routes go here

var httpsServer = https.createServer(credentials, app);

TLS/SSL Encryption is supported by Metasploit. If you want to to include support for encrypted communication, ensure your web server supports or requires TLS or SSL in order to connect.

Authentication

// You can be as sophisticated or as simple as you want
app.use(express.basicAuth(function(user, pass) {
 return user === 'hardcoded' && pass === 'really?!?';
}));

Your Hardware device does not have to support authentication. However, if you want to include it you should use the basic authentication measure used by web servers. Use the RFC 2617

Get Status and Capabilities

Requesting Status

{
  "operational": 0,
  "hw_speciality":
    {
      "automtive": true,
      "sdr": false
    },
  "hw_capabilities":
    {
      "can": true,
      "kline": true
    }
}

// Example of last_10_error log
[
  {
    "msg": "Packet collision detected",
    "when": 1482548041
  },
  {
    "msg": "Duplicate message received",
    "when": 1482548095
  }
]


app.get('/status', function (req, res) {
  //... Gather all the data and return JSON...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ operational: 1, hw_specialty: { automotive: true }, hw_capabilities: { can: true } }, null, 1));
})

Sample Error log

This endpoint retrieves the status of the hardware bridge. This should be used when first connecting to a device to see what the capabilities are. Each time this endpoint is queried the hardware should recheck to ensure the devices

HTTP Request

GET http://example.com/api/status

Response Parameters

There are only a few required parameters:

Parameter Default Description
operational 0 Integer value of HW state: 0 = Unknown, 1 = yes, 2 = no
hw_speciality {} What the device specializes in
hw_capabilities {} List of specific capabilities the device supports
last_10_errors [] Array of the last 10 detected errors
api_version 0.0.1 API version device is compliant with
fw_version 0.0.1 Firmware version of the device
hw_version 0.0.1 Hardware Version
device_name None Optional Hardware device name

hw_specialty

The hardware speciality is a list of major functionality that the hardware device supports. This list loads base level exentions for metasploit. For instance, if automotive is set to true then the automotive extension will automatically be loaded for the session. Devices can support more than one specialty. You do not need to return false for specialties but it could be useful if the device supports additional specialities but they are currently disabled by the hardware.

Current extensions supported by Metasploit:

Specialties Description
automotive Enable the automotive extensions for Metasploit

hw_capabilties

Specifics of the devices capabilities can be reported through this hash. For instance if you have a device that supports different types of buses or hardware interfaces they can be returned through this method. These capabilities are used by modules to determine which types are supported on this device.

Multiple Devices and Hardware Versions

Note: New as of API 0.0.3

Whent there is more than one device attached to a relay and you want to report all the different hardware versions and device names you will return a string seperated by commas for each device. The order of the array should match those reported by the extentions supported_XXX command. For instance, the first device returned from supported_devices (Zigbee) would match the first device in the list.

Parameter Default Description
hw_version “035, 034” Returning more than one connect device with differeing versions
device_name “KILLERB001, KILLERB001” Return two device names for each connect device

Some capabilities are have special meaning:

Special Capabilities Description
custom_methods If set to true, custom_methods will be called to auto-populate the list of custom hardware controls accessible in Metasploit

last_10_errors

The device can report errors that were detected. These errors could be hardware errors or communication errors.

Gathering Statistics

Gather basic usage statistics

{
  "uptime":  3902,
  "packet_stats":  984,
  "last_request": 1482867802,
  "voltage": 11.8
}

app.get('/statistics', function (req, res) {
  // Gather stats to report in JSON
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ /* Current Stats */ }, null, 1));
})

Returns some basic information on the current devices runtime operations.

HTTP Request

GET http://example.com/api/statistics

Response Parameters

All responses are optional.

Paramter Default Description
uptime 0 Seconds of uptime
packet_stats 0 Packets sent through device
last_request 0 Epoch of when the last packet was sent
voltage 0 Current voltage usage

Device Settings

This endpoint is for adjusting settings on the hardware device. This endpoint is optional.

Get Datetime

Get the Date and Time of the device

{
  "system_datetime": 1482866664
}

app.get('/settings/datetime', function (req, res) {
  var epoch = new Date() / 1000;
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ system_datetime: epoch }, null, 1));
})

Gets the datetime stamp of the remote hardware

HTTP Request

GET http://example.com/api/settings/datetime

Response Parameters

Paramter Default Description
system_datetime 0 Epoch

Get Timezone

Returns the current timezone

{
  "system_timezone": "PDT"
}

app.get('/settings/timezone', function (req, res) {
  var timezone = new Date().toString().match(/\(([A-Za-z\s].*)\)/)[1]
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ system_timezone: timezone }, null, 1));
})

Get the timezone reported by the hardware

HTTP Request

GET http://example.com/api/settings/timezone

Response Parameters

Paramter Default Description
system_timezone “” String response such as EST, PDT, etc.

Get IP Configuration

Get the IP Configuration Info

{
  "setup": "dynamic",
  "ip4_addr: "172.16.17.18",
  "ip4_netmask": 255.255.0.0",
  "ip4_gw" : "172.16.0.1",
  "ip6_addr: "fe80::73a7:4cee:f4ac:b7e3",
  "ip6_netmask": "/64",
  "dns": [
    "8.8.8.8",
    "8.8.4.4"
  ]
}

app.get('/settings/ip/config', function (req, res) {
  // Gather and report IP information
});

Get the remote devices IP settings

HTTP Request

GET http://example.com/api/settings/ip/config

Response Parameters

Paramter Default Description
setup “” Reports if the IP was statically or dynamically setup
ip4_addr “172.0.0.1” The current ip4 IP address of the HW device
ip4_netmask “255.255.255.0” IP 4 netmask
ip4_gw “” IP 4 Gateway
ip6_addr “::1” The current ip6 IP address of the HW device
ip6_netmask “” The IP6 Netmask
ip6_gw “” IP6 gateway
dns [] Array of dns addresses defined by “addr:”

Low-level Firmware Control

This endpoint is for low level hardware controls. Typically used for troubleshooting or remote updates. This endpoint is optional.

Reboot Device

{
  "status": "Rebooting"
}

var exec = require('child_process').exec;

function execute(command){
    exec(command, function(error, stdout, stderr));
}

app.get('/control/reboot', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ status: "Rebooting" }, null, 1));
  // You would need the account to be in sudoers file w/o a need for a password
  execute('sudo /sbin/reboot');
});

Reboots the remote device.

HTTP Request

GET http://example.com/api/control/reboot

Response Parameters

Paramter Default Description
status “Not Supported” Reports “Rebooting” if control is supported

Factory Reset

{
  "status": "Resetting"
}

app.get('/control/factory_reset', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ status: "Resetting" }, null, 1));
  // Execute whatever fallback firmware control is supported
});

Resets the device back to its initial settings if supported. This could be used in conjunction with other hardware controls such as a reset button.

HTTP Request

GET http://example.com/api/control/factory_reset

Response Parameters

Paramter Default Description
status “Not Supported” Reports “Resetting” if control is supported

Custom Hardware Methods

Hardware can support functionality that is not originally known to the Metasploit framework. These methods will automatically show up in the hwbridge interface.

Get a list of methods

It is possible to include custom hardware controls by sending method prototypes to the Metasploit framework.

{
  "Methods": [
    {
      "method_name": "rewrite_protected_memory",
      "method_desc": "Overwrites protected memory with specified RFID",
      "args": [
        {
          "arg_name": "RFID",
          "arg_type": "Int",
          "required": true
        }
      ],
      "return": "string"
    }
  ]
}

// To get a list of custom methods
app.get('/custom_methods', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ Methods: [ /* Custom definitions */ ] }, null, 1));
});

HTTP Request

GET http://example.com/api/custom_methods

Response Parameters

The response JSON defines all attributes of the custom methods. See JSON example for more clarificaiton.

Paramter Default Description
Methods [] Array of method hashes
method_name Unique utf8 name that will show up as a command
method_desc A brief description for what the command does
args [] Array of argument definitions
arg_name Unique argument name that will be passed as a URI argument
arg_type Type defines desired type. Validity checking should still be done
required false Is this argument required?
return “nil” How to format the return value

Returned values are return as a hash with key of “value”. The defined return type indicates how the value should be formated and displayed to the end user. Options are:

Return Types Description
nil No return expected
int Integer value
hex Integer value will be convert to a hex and represented with 0x00 syntax
boolean Boolean true or false
float Floating point number
string String will be directly returned

If there is an error you may return “success” as false as well. If you set a return value for “status” the result will be printed to the command line.

Calling a custom method

{
  "value": "Memory updated"
}

// If you had a custom method called "custom/rewrite_protected_memory"
app.get('/custom/rewrite_protected_meory', function (req, res) {
  // if you have an arg_name defined as "rfid"
  var rfid = req.query.rfid;
  // Do you custom work...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ value: "Great success, updated memory" }, null, 1));
});

HTTP Request

The HTTP Request is always a GET request. These are custom URIs that are supported by the hardware and reported via calls to the custom_methods endpoint. For instance, custom_methods defined a method_name of “rewrite_protected_memory” Then the call would be directly off the root:

GET http://example.com/api/rewrite_protected_memory

However, if the method_name was “custom/rewrite_protected_memory” then the command via Metasploit would still be “rewrite_protected_memory” however the URI would be:

GET http://example.com/api/custom/rewrite_protected_memory

Request Paramters

Parameters are defined by the methods “args” attribute. This is an array of possible parameter values. The value types are defined by the “arg_type” definitions however, Metasploit only performs basic validation and the values should still be validated by the hardware. The “required” attribute denotes if the argument is required before the full URI will be created.

Response Parameters

All responses should have a “value”. If the “return” type is set to “nil” then an empty hash can be returned instead. Typically you will want to use the “string” return type as it provides the most control. However, you can use the other types and have Metaplsoit do some formating for you.

Automotive Extension

This end point is for devices that support the automotive hw_specialty.

Get supported buses

Gather supported buses

[
  {"bus_name":"vcan0"},
  {"bus_name":"can0"},
  {"bus_name":"can1"}
]

app.get('/automotive/supported_buses', function (req, res) {
  //... Gather all capabile buses and return an array of bus_names ...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify([ { bus_name: "vcan0" }, { bus_name: "can0" } ], null, 1));
})

Returns a unique name for all supported buses. These names are used as targets for the supported modules.

HTTP Request

GET http://example.com/api/automotive/supported_buses

Response Parameters

Returns an array of active buses.

Paramter Default Description
bus_name [] Array of unique bus_name used as targets for modules

Configure a bus

Sets buad rate of CAN buses

{
  "bitrate": 500000
}

app.get('/automotive/:bus_name/config', function (req, res) {
  var bus = req.params.bus_name;
  //... Report the current bus configuration ...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ bitrate: 500000 }, null, 1));
})

Sets sepcial configurations for a target bus returned by supported_buses.

HTTP Request

GET http://example.com/api/automotive/:bus_name/config

Response Parameters

The current configurations of the targetted bus_name

Paramter Default Description
bitrate 0 Numeric bitrate of the bus, example: 500000 for 500k baud

Send a CAN Packet

Send CAN Packets

{
  "success": true
}

app.get('/automotive/:bus_name/cansend', function (req, res) {
  var bus = req.params.bus_name;
  var id = req.query.id;
  var data = req.query.data;
  //... do the work...
})

Sends a CAN packet. Only required if a canbus is supported by the hardware.

HTTP Request

GET http://example.com/api/automotive/:bus_name/cansend

Query Parameters

Required Parameters

Paramter Default Description
id “0” Hex value of the CAN ID represented as a string. Example: “7DF”
data “” A string representing up ot 8 hex bytes. Example “02FF09”

Response Parameters

Returns success if the packet was able to be sent.

Paramter Default Description
success false Returns true of no errors were detected

Send an ISOTP Packet and wait for response

Handle ISO-TP Requests and responses

/* Example of a packet response */
{  
   "Packets":[  
      {  
         "ID":"7E8",
         "DATA":[  "10", "14", "49", "02", "01", "31", "47", "31" ]
      },
      {  
         "ID":"7E8",
         "DATA":[  "21", "5A", "54", "35", "33", "38", "32", "36" ]
      },
      {  
         "ID":"7E8",
         "DATA":[  "22", "46", "31", "30", "39", "31", "34", "39" ]
      }
   ]
}


app.get('/automotive/:bus_name/isotpsend_and_wait', function (req, res) {
  var bus = req.params.bus_name;
  var srcid = req.query.srcid;
  var dstid = req.query.dstid;
  var data = req.query.data;
  // Optional
  var timeout = req.query.timeout;
  var maxpkts = req.query.maxpkts;
  //... do the work...
})

Sends a packet in the ISO-TP format and then waits for an ISO-TP Styled response.

HTTP Request

GET http://example.com/api/automotive/:bus_name/isotpsend_and_wait

Query Parameters

Required Parameters

Paramter Default Description
srcid Hex value of the Sending CAN ID as a string. Example “7E0”
dstid Hex value of the Receiving CAN ID as a string. Example “7E8”
data A string represeting the data bytes to send. Example: “0902” to get VIN

Optional Parameters

Paramter Default Description
timeout 1500 The timeout to wait for a response.
maxpkts 3 Stop listening for response packets once this number has been received

Response Parameters

Returns success if the packet was able to be sent. When successful a Packets array will also be set with all of the matching packets.

The listener will exit with success being false if timeout happens before maxpkts are reached. If even one packet is recieved the success will be set to true.

Paramter Default Description
success false Returns true of no errors were detected
Packets [] Contains an array of IDs and DATA of the response packets

RF Transceiver Extension

This end point is for devices that support the rftransciiver hw_specialty.

Get supported USB Indexes

Gather supported USB Indexes

{
  "indexes": [ 0 ]
}

app.get('/rftransceiver/supported_idx', function (req, res) {
  //... Gather all capabile buses and return an array of bus_names ...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ indexes: [ 0 ] }, null, 1));
})

Returns a unique index ID for all supported USB indexes. These IDs are used to specify different transceivers if the relay has more than one.

HTTP Request

GET http://example.com/api/rftransceiver/supported_idx

Query Parameters

Required Parameters

Paramter Default Description
idx 0 Index number
freq 0 Frequency, Example: 433000000

Optional Parameters

Paramter Default Description
mhz 24 Mhz

Response Parameters

Returns an array of index.

Paramter Default Description
indexes [] Array of unique ID numbers

Set the Frequency

Sets the Frequency

{
  "success": true
}

app.get('/rftransceiver/:idx/set_freq', function (req, res) {
  var freq = req.params.freq;
  //... Report the current bus configuration ...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the frequency

HTTP Request

GET http://example.com/api/rftransceiver/:idx/set_freq

Response Parameters

Success or failure message

Paramter Default Description
success false Command success

Get supported Modulations

Gets a list of supported modulations

[
  ["2FSK", "GFSK", "ASK/OOK", "MSK", "2FSK/Manchester", "GFSK/Manchester", "ASK/OOK/Manchester", "MSK/Manchester"]
]

app.get('/rftransciever/:idx/get_modulations', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify(["2FSK", "GFSK", "ASK/OOK"], null, 1));
})

Returns a list of all supported modulations. These strings are the keyword used to set a modulation.

HTTP Request

GET http://example.com/api/rftransceiver/:idx/get_modulations

Response Parameters

Returns success if the packet was able to be sent.

Paramter Default Description
[] List of string representation of modulation settings

Set Modulation

Setup a modulation

{
  "success": true
}

app.get('/rftransceiver/:idx/set_modulation', function (req, res) {
  var mod = req.params.mod;
  //... Set the modulation
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets a desired modulation technique. See get_modulations for a list of supported modulations

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_modulation

Query Parameters

Required Parameters

Paramter Default Description
mod “” Modulation name. Example ASK/OOK

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Packet’s Fixed Length

Set fixed length

{
  "success": true
}

app.get('/rftransceiver/:idx/make_packet_flen', function (req, res) {
  var flen = req.params.len;
  //... Set fixed length
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the fixed length value of a packet

HTTP Request

GET http://example.com/api/reftransciever/:idx/make_packet_flen

Query Parameters

Required Parameters

Paramter Default Description
len 0 Fixed length

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Packet’s Variable Length

Set variable length

{
  "success": true
}

app.get('/rftransceiver/:idx/make_packet_vlen', function (req, res) {
  var vlen = req.params.len;
  //... Set variable length
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the variable length value of a packet

HTTP Request

GET http://example.com/api/reftransciever/:idx/make_packet_vlen

Query Parameters

Required Parameters

Paramter Default Description
len 0 Fixed length

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Mode

Set mode TX, RX or IDLE

{
  "success": true
}

app.get('/rftransceiver/:idx/set_mode', function (req, res) {
  var mode = req.params.mode;
  //... Set the mode
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the transmission mode. Options are TX, RX or IDLE

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_mode

Query Parameters

Required Parameters

Paramter Default Description
mode 0 Mode: TX, RX or IDLE

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Enable Packet CRC

Enable CRC

{
  "success": true
}

app.get('/rftransceiver/:idx/enable_packet_crc', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the device to generate a CRC

HTTP Request

GET http://example.com/api/reftransciever/:idx/enable_packet_crc

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Enable Manchester Encoding

Enable manchester encoding

{
  "success": true
}

app.get('/rftransceiver/:idx/enable_manchester', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Enables Manchester encoding

HTTP Request

GET http://example.com/api/reftransciever/:idx/enable_manchester

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Channel

Set channel

{
  "success": true
}

app.get('/rftransceiver/:idx/set_channel', function (req, res) {
  var channel = req.params.channel;
  //... Set the channel
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the channel

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_channel

Query Parameters

Required Parameters

Paramter Default Description
channel 0 Channel number

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Channel Bandwidth

Set channel’s bandwidth

{
  "success": true
}

app.get('/rftransceiver/:idx/set_channel_bandwidth', function (req, res) {
  var bw = req.params.bw;
  //... Set the channel's bandwidth
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the channel bandwidth

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_channel_bandwidth

Query Parameters

Required Parameters

Paramter Default Description
bw 0 Channel bandwidth

Optional Parameters

Paramter Default Description
mhz 24 Mhz

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Channel SPC

Set channel’s spc

{
  "success": true
}

app.get('/rftransceiver/:idx/set_channel_spc', function (req, res) {
  // All params are optional
  var chanspc = req.params.chanpsc;
  var chanspc_m = req.params.chanpsc_m;
  var chanspc_e = req.params.chanpsc_e;
  var mhz = req.params.mhz;
  //... Set the channel's spc
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the channel spc

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_channel_spc

Query Parameters

Optional Parameters

Paramter Default Description
chanspc 0 Main chanspc
chanspc_m 0 If you don’t set chanspc you can set both _m and _e
chanspc_e 0 If you don’t set chanspc you can set both _m and _e
mhz 24 Mhz

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Baud Rate

Set baud rate

{
  "success": true
}

app.get('/rftransceiver/:idx/set_baud_rate', function (req, res) {
  var rate = req.params.rate;
  //... Set the baud rate
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the baud rate

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_baud_rate

Query Parameters

Required Parameters

Paramter Default Description
rate 0 baud rate. Example: 2400

Optional Parameters

Paramter Default Description
mhz 24 Mhz

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Deviation

Set deviation

{
  "success": true
}

app.get('/rftransceiver/:idx/set_deviation', function (req, res) {
  var deviat = req.params.deviat;
  //... Set the deviation
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the deviation

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_deviation

Query Parameters

Required Parameters

Paramter Default Description
deviat 0 Deviat value

Optional Parameters

Paramter Default Description
mhz 24 Mhz

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Sync Word

Set sync word

{
  "success": true
}

app.get('/rftransceiver/:idx/set_sync_word', function (req, res) {
  var word = req.params.word;
  //... Set the sync word
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the sync word.

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_sync_word

Query Parameters

Required Parameters

Paramter Default Description
word 0 Sync Word

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Sync Mode

Set sync Mode

{
  "success": true
}

app.get('/rftransceiver/:idx/set_sync_mode', function (req, res) {
  var mode = req.params.mode;
  //... Set the sync mode
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the sync mode. Sets the accuracy of the sync

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_sync_mode

Query Parameters

Required Parameters

Paramter Default Description
mode 0 Sync Mode

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Max Power

Set the power to max

{
  "success": true
}

app.get('/rftransceiver/:idx/set_maxpower', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the maximum power level. Frequency should be set first

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_maxpwer

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Set Power Level

Set the power level

{
  "success": true
}

app.get('/rftransceiver/:idx/set_power', function (req, res) {
  var power = req.params.power;
  //... Set the power level
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the power level. Power can vary depending on frequency

HTTP Request

GET http://example.com/api/reftransciever/:idx/set_power

Query Parameters

Required Parameters

Paramter Default Description
power 0 Power level

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Transmit a packet

Send a packet

{
  "success": true
}

app.get('/rftransceiver/:idx/rfxmit', function (req, res) {
  var data = req.params.data;
  // Optional
  var repeat = req.params.repeat;
  var offset = req.params.offset;
  //... Transmit the packet
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Transmits the packet. Optionally you can set the repeat amount and the data offset. The data is Base64 encoded and can contain binary information

HTTP Request

GET http://example.com/api/reftransciever/:idx/rfxmit

Query Parameters

Required Parameters

Paramter Default Description
data 0 Base64 Encoded binary blob

Optional Parameters

Paramter Default Description
repeat 0 Repeat transmition X times
offset 0 Data offset to use

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Receive a packet

Recieves packets

{
  "success": true
}

app.get('/rftransceiver/:idx/rfrecv', function (req, res) {
  // Optional
  var timeout = req.params.timeout;
  var blocksize = req.params.blocksize;
  //... Transmit the packet
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Recieves a packet. Packets are sent over Base64 encoded and can contain binary data. A timestamp is also included

HTTP Request

GET http://example.com/api/reftransciever/:idx/rfxmit

Query Parameters

Optional Parameters

Paramter Default Description
timeout 0 Timeout value
blocksize 0 Blocksize

Response Parameters

Paramter Default Description
data “” Base64 Encoded data
ts 0 Timestamp

Zigbee Extension

This end point is for devices that support Zigbee controls such as Killerbee

Get supported Killerbee Devices

Gather supported USB Indexes

{
  "devices": [ '3:35' ]
}

app.get('/zigbee/supported_devices', function (req, res) {
  //... Gather all capabile zigbee usb IDs and return an array of IDs ...
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ devices: [ '3:35' ] }, null, 1));
})

Returns a unique index ID for all supported Zigbee devices. These IDs are used to specify different transceivers if the relay has more than one.

HTTP Request

GET http://example.com/api/zigbee/supported_devices

Response Parameters

Returns an array of index.

Paramter Default Description
devices [] Array of unique ID strings

Set the Channel

Sets the Channel

{
  "success": true
}

app.get('/zigbee/:id/set_channel', function (req, res) {
  var chan = req.params.chan;
  //... Change the channel
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Sets the channel from 11-25

HTTP Request

GET http://example.com/api/zigbee/:id/set_channel

Query Parameters

Sets the target channel

Paramter Default Description
chan Channel number 11-25

Response Parameters

Success or failure message

Paramter Default Description
success false Command success

Inject a raw packet

Inject a raw packet

{
  "success": true
}

var URLSafeBase64 = require('urlsafe-base64');
app.get('/zigbee/:id/inject', function (req, res) {
  var data = URLSafeBase64.decode(req.params.data);
  // Inject raw packet (may need special firmware)
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Injects a raw packet to the current channel.

HTTP Request

GET http://example.com/api/zigbee/:id/inject

Query Parameters

Sets the target channel

Paramter Default Description
data Raw data in a string to be sent

Response Parameters

Returns success if the packet was able to be sent.

Paramter Default Description
success false Command success

Receive a packet

Receive a packet

{
  "data": <base64 encoded data>
  "valid_crc": <non-zero value if valid>
  "rssi": <rssi value>
}

var URLSafeBase64 = require('urlsafe-base64');
app.get('/zigbee/:id/recv', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ data: URLSafeBase64.encode(data), valid_crc: crc: rssi: rssi }, null, 1));
})

Receives a raw packet from the current channel

HTTP Request

GET http://example.com/api/zigbee/:id/recv

Response Parameters

Paramter Default Description
data {} Base64 encoded raw data
valid_crc 0 Non-zero value if valid
rssi Signal Strength

Enable Sniffer Mode

Enables Receive mode

{
  "success": true
}

app.get('/zigbee/:id/sniffer_on', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Enables receive mode

HTTP Request

GET http://example.com/api/zigbee/:id/sniffer_on

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Disable Sniffer Mode

Disables Receive mode

{
  "success": true
}

app.get('/zigbee/:id/sniffer_off', function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(JSON.stringify({ success: true }, null, 1));
})

Disables sniffer. Allows for chaning settings such as channel

HTTP Request

GET http://example.com/api/zigbee/:id/sniffer_off

Response Parameters

Paramter Default Description
success false Returns true of no errors were detected

Errors

Default all unknown requests to return a JSON with status of not supported.

All unhandled and unknown requests return “not supported”

{
  "status": "not supported"
}

// Catches all unknown responses and returns "not supported"
// 404 Response not necessary
app.get('*', function(req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.status(404).send(JSON.stringify({ status: "not supported" }, null, 1));
});
json javascript