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.
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 RESTful service, click the Tools > Preferences menu item in the main menu, then press the “Remote access service” toggle button (see the figure below); 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.
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.
The Remote Access Service provides 5 resources: /capture , /sniffers , /adapters /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 /adapters replace the sniffers, they support different functions both for their configuration and their use. 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
Returns information about the current capture.
An XML document with the information about the current capture.
A GET request to the URL http://localhost:19501/capture?offset=10&limit=2 , produces a response with code 200, and the following document:
xmlns="urn:ubilogix:services"> Count="48454" Offset="10" Limit="2"> Id="11"> Beacon File Normal 008038AA1A0000FFCF80000022841111111111111111FFFFFF00FFFF Id="12"> Beacon Request File Normal 03087DFFFFFFFF07FFFF
Performs the specified action on the current capture.
The capture was successfully cleared or, it is being exported but the process is not yet completed.
There are not packets to clear.
The export process failed.
The request can’t be processed because Ubiqua is currently busy.
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.
Returns a list of adapters connected to Ubiqua.
An XML document with the list of adapters.
A GET request to the URL http://localhost:19501/adapters , produces a response with code 200, and the following XML document:
xmlns="urn:ubilogix:services"> Id="local_99" Link="http://192.168.0.6:19501/adapters/local_99"> IsAvailable="true" IsConnected="true" IsStarted="false" IsCustom="false" /> Protocol="Thread" Channel="12" SelectedApp="Packet Sniffer" Radio="12 (0x0C), 2410 MHz, O-QPSK_250"> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="12" /> Id="local_30352" Link="http://192.168.0.6:19501/adapters/local_30352"> IsAvailable="false" IsConnected="false" IsStarted="false" IsCustom="false" /> Id="local_0000000d5d" Link="http://192.168.0.6:19501/adapters/local_0000000d5d"> IsAvailable="true" IsConnected="true" IsStarted="false" IsCustom="false" /> Protocol="Zigbee" Channel="11" SelectedApp="Ubisys Sniffer" Radio="11 (0x0B), 2405 MHz, O-QPSK_250"> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="11" />
GET /adapters/
Returns the information of the adapter with the specified adapter ID.
Gets an XML document with the status of the adapter.
The adapter with the specified ID was not found on the list of available adapters.
A GET request to the URL http://localhost:19501/adapters/local_99 , produces a response with code 200, and the following XML document:
Id="local_99" xmlns="urn:ubilogix:services"> IsAvailable="true" IsConnected="true" IsStarted="false" IsCustom="false" /> Protocol="Thread" Channel="12" SelectedApp="Packet Sniffer" Radio="12 (0x0C), 2410 MHz, O-QPSK_250"> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="12" />
Returns the supported configuration of the adapter with the specified ID.
Gets and XML document with the supported configuration of the adapter.
The adapter with the specified ID was not found the list of available adapters.
A GET request to the URL http://localhost:19501/adapters/local_99/configurations , produces a response with code 200, and the following document:
Id="local_99" xmlns="urn:ubilogix:services"> IsAvailable="true" IsConnected="true" IsStarted="false" IsCustom="false" /> Protocol="Zigbee" Channel="11" SelectedApp="Packet Sniffer" Radio="11 (0x0B), 2405 MHz, O-QPSK_250" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="11" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="12" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="14" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="16" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="18" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="21" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="17" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="25" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="15" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="20" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="23" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="24" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="26" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="11" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="13" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="19" /> Modulation="O-QPSK" DataRate="250" FrequencyBand="2400" Channel="22" />
PUT /adapters/
Starts or stops the adapter of the specified ID
Starts or stops a adapter as instructed by the action parameter.
The adapter with the specified ID was not found on the list of available adapters.
The adapter with the specified ID is already in the requested state.
A PUT request to the URL http://localhost:19501/sniffers/local_99 , with the following request body: action=start , protocol=Zigbee , modulation=O-QPSK , channel=13 , rate=250 and frequencyBand=2400 of content-type application/x-www-form-urlencoded , produces a response with code 200 and an empty body. The device was started.
Returns a list of the sniffer devices connected to Ubiqua.
An XML document with the list of sniffer devices.
A GET request to the URL http://localhost:19501/sniffers , produces a response with code 200, and the following document:
xmlns="urn:ubilogix:services"> Id="USB5255" Link="http://10.0.1.9:19501/sniffers/USB5255"> false true 25 6 Id="COM35" Link="http://10.0.1.9:19501/sniffers/COM35"> false true 25 11 Id="01112004" Link="http://10.0.1.9:19501/sniffers/01112004"> false false 11 0
GET /sniffers/
Returns the information of the sniffer device with the specified ID.
Gets an XML document with the status of the sniffer device with the specified ID.
The sniffer with the specified ID was not found on the list of available sniffer devices.
A GET request to the URL http://127.0.0.1:19501/sniffers/USB5255 , produces a response with code 200, and the following document:
Id="Texas Instruments CC2531 [USB5255]" xmlns="urn:ubilogix:services"> false true 25 0
PUT /sniffers/
Starts or stops the sniffer device of the specified ID.
Starts or stops a sniffer device as instructed by the action parameter.
The sniffer cannot start channel out of range or protocol not supported.
The sniffer with the specified ID was not found on the list of available sniffer devices.
The sniffer with the specified ID is already in the requested state.
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.
Returns a list of the filters in Ubiqua.
An XML document with the list of filters.
A GET request to the URL http://localhost:19501/filters , produces a response with code 200, and the following document:
xmlns="urn:ubilogix:services"> Name="Time Delta is 0.000000" IsEnabled="true" Link="http://10.0.1.8:19501/filters/0" /> Name="channel 21" IsEnabled="false" Link="http://10.0.1.8:19501/filters/1" />
GET /filters/
Returns the status and conditions of the filter with the specified ID.
Gets an XML document with the status and conditions of the filter with the specified ID.
The filter with the specified ID was not found on the list of filters.
A GET request to the URL http://127.0.0.1:19501/filters/2 , produces a response with code 200, and the following document:
Sequence Number is 10 true Match="All"> SequenceNumber Sequence Number Is Integer 8 10 />
Enables or disables the filter.
Enables or disables the filter as instructed by the \texttt parameter.
The filter does not exist, or the action is unknown.
The filter cannot be enabled or disabled when a task is running.
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.
Returns a list of the Security keys in Ubiqua.
An XML document with the list of security keys.
A GET request to the URL http://localhost:19501/keys , produces a response with code 200, and the following document:
xmlns="urn:ubilogix:services"> Type="NetworkKey">76:D9:74:54:AE:A1:C6:1B:24:A1:90:96:0E:D1:D2:39 Type="LinkKey">A8:53:6D:BC:99:11:5B:E1:31:B5:F4:FD:A5:35:60:42 Type="LinkKey">E2:D6:45:F2:8C:A8:B0:E8:EF:7E:CC:E0:4C:BF:8D:BE
Inserts a new security key in Ubiqua.
New security key was added with the specified key type.
The key type is invalid, or the key length is invalid.
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.
Returns a list of the addresses in Ubiqua.
An XML document with the list of addresses.
A GET request to the URL http://localhost:19501/addresses , produces a response with code 200, and the following document:
0000000000000000 0000 7C89 ECAA 001DB70000033D6D F02D
Inserts a new relationship of long address and short address.
New addresses relationship was added.
Either the longAddress or shortAddress value is invalid.
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.
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 < false true 25 0 * Connection #0 to host localhost left intact * Closing connection #0
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
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
The code snippets listed in this chapter are written in the C# programming language and are intended to be used with the .NET Framework.
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()); >
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()); >
// 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()); >
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.
To run your test of Ubiqua Services you can download Ubiqua Postman Collection.
The Remote Access Service waits for a request once it has been sent and begins to process it. It some action will surely take a long time and will cause the client to cancel the connection established with the server in Ubiqua. In this case, the timeout supported by the HTTP specification is over and the request will fail.
It is important also to talk about what happens when the network interface card fails, once the connection between the client and the server fails because the client terminated the session due to a network problem it will also fail.