Ubiqua Services

Ubiqua Protocol Analyzer provides a number of services exposing a limited set of the functionality available throughout the application as Web resources. The Remote Access Service is one of such services. In this chapter you will find the specification of its interface containing the provided resources, what HTTP methods are allowed, what the data representation formats are, and some examples of what you can expect as service outputs.

Remote Access Service

Enabling the Service

At the bottom right of Ubiqua there is a server icon that represents the status of your RESTful service, this can have 2 different states as shown in the image below, the left icon which is the default status appears when the service is not enabled and the icon with the green circle appears when the service is running.

To enable the service, you can press the previously mentioned icon, or go to Tools > Options… in the main menu (see the figure below) and check the "Enable Remote Access Service" box; this box does not denote the service status, it only enables the service. A label showing the service status is next to the right of the "Listening port:" box. The default port is 19501, to specify another one use the "Listening port:" option. The RESTful service will start after you click on the OK button. If you keep the enable option checked, the service will start as soon as the application starts. Once the application has started the default icon will be updated with the server icon with the green circle.

Security Notice

As of Ubiqua 2.0, for better security and user protection, the Remote Services functionality requires an administrator to authorize the use of the network port assigned to Ubiqua. You can authorize the port by running the following command with a privileged account:

netsh http add urlacl url=http://*:19501/ user=Everyone listen=yes
The parameter user may vary depending on the language in which your operating system is, for example in English as shown in the command above user=everyone, in Spanish and Portuguese user=todos, Swedish user=alla, German user=Jeder, French user="Tout le monde", Dutch user=iedereen, Russian user=все.

If you are having problems connecting to the Remote Access Service, your Operating System may be blocking access to the configured port, refer to this link for more information.

If you want to secure the access, the service supports HTTP Basic Authentication. Just check the "Require authentication" box and provide a username and a password.

The service is still enabled if an error occurs and the status label will indicate the current status of the service.

Available Resources

The Remote Access Service provides 5 resources: /capture, /sniffers, /filters, /keys and /addresses. The /capture resource represents the current capture in Ubiqua, and it can be used to retrieve the current number of packets and a specific range of packets, to export the capture file to the local file system, or to clear all the packets. The /sniffers resource represents the sniffer devices currently attached and available in Ubiqua, it can be used to retrieve the list of all devices, the status of a specific device, and to start or stop a sniffer. The /filters resource represents the current filters in Ubiqua, and it can be used to retrieve the list of filters, to enable or disable a filter. The /keys resource represents the current security keys in Ubiqua, and it can be used to retrieve the list of security keys, and to insert a new security key. The /addresses resource represents the current addresses in Ubiqua, and it can be used to retrieve the list of addresses, and to insert a new relationship of long address and short address.

The schema document for this service responses is located at

http://www.ubilogix.com/api/v1/services.xsd

Current Capture

GET /capture

Returns information about the current capture.

Request Parameters

  • offset – An integer accepting positive numbers and zero 0. The offset of the packets to retrieve.

  • limit – An integer accepting positive numbers and zero 0. The number of packets to retrieve.

Response Code 200 (OK)

An XML document with the information about the current capture.

Sample Request

A GET request to the URL http://localhost:19501/capture?offset=10&limit=2, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Capture xmlns="urn:ubilogix:services">
  <Packets Count="48454" Offset="10" Limit="2">
   <Packet Id="11">
   <Info>Beacon</Info>
   <Source>File</Source>
    <Status>Normal</Status>
   <Raw>008038AA1A0000FFCF80000022841111111111111111FFFFFF00FFFF</Raw>
  </Packet>
  <Packet Id="12">
   <Info>Beacon Request</Info>
   <Source>File</Source>
  <Status>Normal</Status>
   <Raw>03087DFFFFFFFF07FFFF</Raw>
  </Packet>
 </Packets>
</Capture>

PUT /capture

Performs the specified action on the current capture.

Request Parameters

  • action – A string with one of the following values:
    • clear, to reset the capture.
    • save, to store the capture log in Ubiqua file format on the specified file location.
    • export, to store the capture log in other file format on the specified file location. Use one of the valid file extensions: .txt, .xls, .csv and .opml.
    • load, to open a file capture with any supported file format of Ubiqua.
  • filename – A string with the file name to export the capture to or, the file name to open capture.

Response Code 200 (Created)

  • The capture was successfully exported.
  • The file is created with no packet information if there is no data to export.

Response Code 202 (Accepted)

  • The capture was successfully cleared or, it is being exported but the process is not yet completed.

Response Code 400 (Bad Request)

  • The file type of the file specified in the filename parameter is not supported by Ubiqua.

Response Code 500 (Internal Server Error)

  • The export process failed.

Sample Requests

Save a capture by sending a PUT request to the URL http://localhost:19501/capture, with the following request body: action=save&filename=C:\test.cubx and a content-type request header containing application/x-www-form-urlencoded, produces a response with code 200 and an empty body.

Export a capture by sending a PUT request to the URL http://localhost:19501/capture, with the following request body: action=export&filename=C:\test.txt and a content-type request header containing application/x-www-form-urlencoded, produces a response with code 200 and an empty body.

Sniffer Devices

GET /sniffers

Returns a list of the sniffer devices connected to Ubiqua.

Response Code 200 (OK)

An XML document with the list of sniffer devices.

Sample Request

A GET request to the URL http://localhost:19501/sniffers, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Devices xmlns="urn:ubilogix:services">
  <Sniffers>
    <Sniffer Id="USB5255" Link="http://10.0.1.9:19501/sniffers/USB5255">
      <IsStarted>false</IsStarted>
      <IsPlugged>true</IsPlugged>
      <Channel>25</Channel>
      <Protocol>6</Protocol>
    </Sniffer>
    <Sniffer Id="COM35" Link="http://10.0.1.9:19501/sniffers/COM35">
      <IsStarted>false</IsStarted>
      <IsPlugged>true</IsPlugged>
      <Channel>25</Channel>
      <Protocol>11</Protocol>
    </Sniffer>
    <Sniffer Id="01112004" Link="http://10.0.1.9:19501/sniffers/01112004">
      <IsStarted>false</IsStarted>
      <IsPlugged>false</IsPlugged>
      <Channel>11</Channel>
      <Protocol>0</Protocol>
    </Sniffer>
  </Sniffers>
</Devices>

GET /sniffers/{id}

Returns the information of the sniffer device with the specified ID.

Response Code 200 (OK)

Gets an XML document with the status of the sniffer device with the specified ID.

Response Code 404 (Not Found)

The sniffer with the specified ID was not found on the list of available sniffer devices.

Sample Request

A GET request to the URL http://127.0.0.1:19501/sniffers/USB5255, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Sniffer Id="Texas Instruments CC2531 [USB5255]" xmlns="urn:ubilogix:services">
  <IsStarted>false</IsStarted>
  <IsPlugged>true</IsPlugged>
  <Channel>25</Channel>
  <Protocol>0</Protocol>
</Sniffer>

PUT /sniffers/{id}

Starts or stops the sniffer device of the specified ID.

Request Parameters

  • action – A string with one of the following values:
    • start, to start the sniffer.
    • stop, to stop the device.
  • channel – A value between 11 and 26 representing the physical channel (optional).
  • protocol – A string with one of the following supported values (optional): IEEE 802.15.4-2003, IEEE 802.15.4-2006, Zigbee, IP, Synkro RF, Raw Data, PopNet, Zigbee RF4CE, Zigbee IP, JenNet IP, IETF 6LoWPAN.

Response Code 200 (OK)

Starts or stops a sniffer device as instructed by the action parameter.

Response Code 400 (Bad Request)

The sniffer can not start: channel out of range or protocol not supported.

Response Code 404 (Not Found)

The sniffer with the specified ID was not found on the list of available sniffer devices.

Response Code 503 (Service Unavailable)

The sniffer with the specified ID is already in the requested state.

Sample Request

A PUT request to the URL http://localhost:19501/sniffers/USB5255, with the following request body: action=start, channel=16 and modulation=OQPSK_250 of content-type application/x-www-form-urlencoded, produces a response with code 200 and an empty body. The device was started.

Filters

GET /filters

Returns a list of the filters in Ubiqua.

Response Code 200 (OK)

An XML document with the list of filters.

Sample Request

A GET request to the URL http://localhost:19501/filters, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Filters xmlns="urn:ubilogix:services">
  <Filter Name="Time Delta is 0.000000" IsEnabled="true" Link="http://10.0.1.8:19501/filters/0" />
  <Filter Name="channel 21" IsEnabled="false" Link="http://10.0.1.8:19501/filters/1" />
</Filters>

GET /filters/{id}

Returns the status and conditions of the filter with the specified ID.

Response Code 200 (OK)

Gets an XML document with the status and conditions of the filter with the specified ID.

Response Code 404 (Not Found)

The filter with the specified ID was not found on the list of filters.

Sample Request

A GET request to the URL http://127.0.0.1:19501/filters/2, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Filter>
  <Name>Sequence Number is 10</Name>
  <IsEnabled>true</IsEnabled>
  <Conditions Match="All">
    <Condition>
      <TargetName>SequenceNumber</TargetName>
      <TargetDisplayName>Sequence Number</TargetDisplayName>
      <Operator>Is</Operator>
      <TargetType>Integer</TargetType>
      <TargetLength>8</TargetLength>
      <TargetValue>10</TargetValue>
      <TargetAdditionalValue />
    </Condition>
  </Conditions>
</Filter>

PUT /filters

Enables or disables the filter.

Request Parameters

  • action – A string with one of the following values:
    • enable, to enable the filter.
    • disable, to disable the filter.
  • filter – A string with the filter name.

Response Code 200 (OK)

Enables or disables the filter as instructed by the exttt{action} parameter.

Response Code 400 (Bad Request)

The filter does not exist, or the action is unknown.

Response Code 503 (Service Unavailable)

The filter cannot be enabled or disabled when a task is running.

Sample Request

A PUT request to the URL http://localhost:19501/filters, with the following request body: action=enable&filter=Frame%20Type%20is%20Command of content-type application/x-www-form-urlencoded, produces a response with code 200 and an empty body. The filter was enabled.

Security Keys

GET /keys

Returns a list of the Security keys in Ubiqua.

Response Code 200 (OK)

An XML document with the list of security keys.

Sample Request

A GET request to the URL http://localhost:19501/keys, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Keys xmlns="urn:ubilogix:services">
 <Key Type="NetworkKey">76:D9:74:54:AE:A1:C6:1B:24:A1:90:96:0E:D1:D2:39</Key>
 <Key Type="LinkKey">A8:53:6D:BC:99:11:5B:E1:31:B5:F4:FD:A5:35:60:42</Key>
 <Key Type="LinkKey">E2:D6:45:F2:8C:A8:B0:E8:EF:7E:CC:E0:4C:BF:8D:BE</Key>
</Keys>

POST /keys

Inserts a new security key in Ubiqua.

Request Parameters

  • type – A string with one of the following supported values: PopNetKey, RF4CEKey, NetworkKey, LinkKey, Trust-CenterMasterKey, IEEE-802.15.4-2006Key.
  • key – A string with the new security key to add. The security key length must be 128 bits.

Response Code 202 (Accepted)

New security key was added with the specified key type.

Response Code 400 (Bad Request)

The key type is invalid, or the key length is invalid.

Sample Request

A POST request to the URL http://localhost:19501/keys, with the following request body: type=NetworkKey&key=64:B9:99:95:4D:B1:F9:0F:20:F6:80:02:FB:FE:6F:C4 of content-type application/x-www-form-urlencoded, produces a response with code 202 and an empty body. The security key was added.

Network Addresses

GET /addresses

Returns a list of the addresses in Ubiqua.

Response Code 200 (OK)

An XML document with the list of addresses.

Sample Request

A GET request to the URL http://localhost:19501/addresses, produces a response with code 200, and the following document:

<?xml version="1.0" encoding="UTF-8"?>
<Addresses>
 <AddressRelation>
  <LongAddress>0000000000000000</LongAddress>
  <ShortAddressList>
   <ShortAddress>0000</ShortAddress>
   <ShortAddress>7C89</ShortAddress>
   <ShortAddress>ECAA</ShortAddress>
  </ShortAddressList>
 </AddressRelation>
 <AddressRelation>
  <LongAddress>001DB70000033D6D</LongAddress>
  <ShortAddressList>
   <ShortAddress>F02D</ShortAddress>
  </ShortAddressList>
 </AddressRelation>
</Addresses>

POST /addresses

Inserts a new relationship of long address and short address.

Request Parameters

  • longAddress – The long address to add, with a length of 8 bytes.
  • shortAddress – The short address to relate with the specified long address, with a length of 2 bytes.

Response Code 202 (Accepted)

New addresses relationship was added.

Response Code 400 (Bad Request)

Either the longAddress or shortAddress value is invalid.

Sample Request

A POST request to the URL http://localhost:19501/addresses, with the following request body: longAddress=001DB70000033D6D&shortAddress=40EA of content-type application/x-www-form-urlencoded, produces a response with code 202 and an empty body. The addresses relationship was added.

Using The Command Line

If you prefer to interact with Ubiqua services from the command line you can use cURL, a free command line tool to send HTTP requests. Download cURL from http://curl.haxx.se/. This section shows some examples on how to use cURL with Ubiqua.

Getting the Sniffers List

C:>curl -v "http://localhost:19501/sniffers"
* About to connect() to localhost port 19501 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 19501 (#0)
> GET /sniffers HTTP/1.1
> User-Agent: curl/7.21.6 (i386-pc-win32) libcurl/7.21.6 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:19501
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Length: 341
< Content-Type: application/xml
< Server: Ubiqua-RemoteControl/1.3.2183 Microsoft-HTTPAPI/2.0
< Date: Wed, 25 Sep 2013 00:18:04 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<Devices xmlns="urn:ubilogix:services">
  <Sniffers>
    <Sniffer Id="01TP2RLY" Link="http://10.0.1.8:19501/sniffers/01TP2RLY">
      <IsStarted>false</IsStarted>
      <IsPlugged>true</IsPlugged>
      <Channel>25</Channel>
      <Protocol>0</Protocol>
    </Sniffer>
  </Sniffers>
</Devices>
* Connection #0 to host localhost left intact
* Closing connection #0

Starting a Sniffer

C:>curl -v -X PUT -d "action=start" "http://localhost:19501/sniffers/01TP2RLY"
* About to connect() to localhost port 19501 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 19501 (#0)
> PUT /sniffers/01TP2RLY HTTP/1.1
> User-Agent: curl/7.21.6 (i386-pc-win32) libcurl/7.21.6 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:19501
> Accept: */*
> Content-Length: 12
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Ubiqua-RemoteControl/1.3.2183 Microsoft-HTTPAPI/2.0
< Date: Wed, 25 Sep 2013 00:12:34 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0

Saving the Capture Log

C:>curl -v -X PUT -d "action=save&filename=c:data.pcap" http://localhost:19501/capture
* About to connect() to localhost port 19501 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 19501 (#0)
> PUT /capture HTTP/1.1
> User-Agent: curl/7.21.6 (i386-pc-win32) libcurl/7.21.6 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:19501
> Accept: */*
> Content-Length: 35
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Ubiqua-RemoteControl/1.3 Microsoft-HTTPAPI/2.0
< Date: Wed, 25 Apr 2012 01:20:03 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0

Sample Source Code

The code snippets listed in this chapter are written in the C# programming language and are intended to be used with the .NET Framework.

Getting the Sniffers List

using System;
using System.IO;
using System.Net;  
using System.Text;  

// Create the web request  
HttpWebRequest request = WebRequest.Create(
    "http://localhost:19501/sniffers") as HttpWebRequest;  

// Get response  
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)  
{  
    // Get the response stream  
    StreamReader reader = new StreamReader(response.GetResponseStream());  

    // Console application output  
    Console.WriteLine(reader.ReadToEnd());  
}

Starting a Sniffer

using System.Web;  

Uri address = new Uri("http://localhost:19501/sniffers/USB5255");  

// Create the web request  
HttpWebRequest request = WebRequest.Create(address) as HttpWebRequest;  

// Set type to PUT  
request.Method = "PUT";  
request.ContentType = "application/x-www-form-urlencoded";  

// Create the data we want to send  
string action = "start";  

StringBuilder data = new StringBuilder();  
data.Append("action=" + HttpUtility.UrlEncode(action));

// Create a byte array of the data we want to send  
byte[] byteData = UTF8Encoding.UTF8.GetBytes(data.ToString());  

// Set the content length in the request headers  
request.ContentLength = byteData.Length;  

// Write data  
using (Stream putStream = request.GetRequestStream())  
{  
    putStream.Write(byteData, 0, byteData.Length);  
}  

// Get response  
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)  
{  
    // Get the response stream  
    StreamReader reader = new StreamReader(response.GetResponseStream());  

    // Console application output  
     Console.WriteLine(reader.ReadToEnd());  
}

Getting the Capture Status With Authentication

// Create the web request  
HttpWebRequest request   
    = WebRequest.Create("http://localhost:19501/capture") as HttpWebRequest;  

// Add authentication to request  
request.Credentials = new NetworkCredential("test", "test");  

// Get response  
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)  
{  
    // Get the response stream  
    StreamReader reader = new StreamReader(response.GetResponseStream());  

    // Console application output  
    Console.WriteLine(reader.ReadToEnd());  
}

Running Ubiqua As Server

To run Ubiqua as a server just add the /server argument to your Ubiqua shortcut. Or run Ubiqua from the command line as Ubiqua.exe /server. Alternatively, if Ubiqua is already running, select the Window > Minimize To Tray menu item. ```

Postman Collection for Debug and Testing

To run your test of Ubiqua Services you can download this Postman Collection.