Perceptor API specifications

Application Version: 3.2

QBOID Confidential and Proprietary Information

Perceptor products provide 2 different sets of APIs that would cover different use case scenarios:

• WiFi API: Designed to transmit data acquired with the QBOID applications to a remote server either on premise or on the Internet.
• Android Intent API: Designed to embed the QBOID functionalities into the workflow of an Android or Web application.

In addition, Perceptor products place at the disposal the following features:

• Configuration Import/Export: Designed to easily import and export devices' configurations using files or QR codes.

Supported applications

This documentation covers the following M2 applications developed and maintained by QBOID:

• Item and Parcel Dimensioning App
  Throughout this document, it will be referred to as Parcel
  This application enables the automatic measurement of the length, width, and height of both cuboidal and irregular-shaped items and parcels. It can optionally integrate with Bluetooth scales for seamless weight acquisition.
  When the M2 device is connected to the S1 accessory, the same application is used for operation.

• Pallet Dimensioning App
  Throughout this document, it will be referred to as Pallet
  This application automatically computes the dimensions of a pallet (length, width, and height) by analyzing individual faces. This method allows dimensioning even when the entire pallet is not fully visible from a single perspective.

Table of content

Common definitions and structures

Term Definitions

Device

The QBOID equipment responsible for generating dimensioning records. It can be either a Perceptor M2 or S1.

Server

The system that receives and processes dimensioning records from the QBOID device.

Dimensioning Record

A dimensioning record is a structure containing the information about a single item for either the WiFi or the Intent APIs. It is generally formatted as a JSON string with a structure like the following:

{
  "timestamp": "2021\/02\/14 07:19:38",
  "l": 195,
  "w": 165,
  "h": 72,
  "weight": 7709,
  "barcode": "845973030506",
  "shape": "Cuboidal",
  "device": "FH0402211100001",
  "note": "",
  "attributes": {
    "hazmat": "true"
  },
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEU..."
}

Basic Message structure

Advanced Encoding Info

Escaping

String fields are escaped as per JSON standard, more specifically:

Image encoding

Images are encoded in the JSON request as a Data URI scheme with a base64 encoding adhering RFC-2045.

Following is an example of an encoded image:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAAHklEQVR42mP8z8AARNQDjKMGjho4auCogaMGjlQDAUwCJ+0NBcXlAAAAAElFTkSuQmCC

Note: Previous string can be copied and pasted to browser address bar to visualize the image.

Note: RFC-2045 specification requires that: The encoded output stream must be represented in lines of no more than 76 characters each.. For that reason, the encoded images will contain line breaks (i.e.: \n) that must be ignored by the decoding software.

WiFi API

This is a REST-like API where a JSON message is sent to a local or internet HTTP endpoint, and is designed to be familiar to developers doing client server web development.

Once the scan event is completed, either manually by an operator specific key press, or automatically by QBOID software, the dimensioning record is immediately queued up for offloading to a remote resource, e.g. a WMS system or manifesting software.

API Description

The Device will send a POST request with a JSON body to the HTTP endpoint defined in its configuration expecting a 200-299 HTTP response code.

M2 API settings

There are two groups of settings that can impact the data transmitted through the WiFi API:

• Acquisition is a collection of parameters that will affect the data acquisition during the dimensioning process. Adjusting these settings will not affect the sequences already collected, unless otherwise specified.
• WiFi API is a collection of parameters for configuring the data transmitted over WiFi. Changing these settings will affect the sequences already collected, unless otherwise specified.

Acquisition settings

_{Added in 2.4.0}

Acquisition parameters can be configured in the M2 applications.

WiFi API settings

Optional fields, image format and endpoint can be configured in the M2 applications in the section: Settings -> Data Settings -> WiFi API.

Custom request header settings

_{Added in 2.4.2}
Under the section Settings -> Data Settings -> WiFi API -> Custom request header, the HTTP/HTTPS headers can be customized.

HTTP request

HTTP request is configured as follows:

A response code in the range 200-299 is expected as a response.

Sample RAW TCP Message:

POST /newEntry HTTP/1.1
Content-Type: application/json; utf-8
Accept: application/json
User-Agent: Dalvik/2.1.0 (Linux; U; Android 8.1.0; Scorpio Build/V008R001)
Host: 192.168.7.103:5000
Connection: Keep-Alive
Accept-Encoding: gzip
Content-Length: 199

{"timestamp":"2021\/02\/25 02:16:25","l":266,"w":203,"h":72,"weight":6807,"barcode":"X001SS387V","shape":"Irregular","device":"FH0402211100001","note":"QWERTY","attributes":{"batt":"false","hazmat":"true"}}

HTTPS support

_{Added in 2.1.0}

HTTP over TLS can be used by simply defining https as protocol in the URL of the endpoint.
If the server's SSL certificate was issued by a well-known Certificate Authority (CA), no further action is necessary.

Self-signed server certificate

A self-signed certificate is one that is signed with the servers own private key instead of being signed by a CA.
If the server is using a self-signed certificate, adding the certificate to the Perceptor M2 (see link) will be necessary. Failure to do so will throw the following error when the M2 is attempting to communicate with the server:

javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.

Generate the self-signed certificate

Following is an example on how to create a self-signed certificate using OpenSSL command line tool

openssl req -x509 -newkey rsa:4096 -keyout self_key.pem -out self_cert.pem -sha256 -days 365 -nodes \
 -subj "/C=US/ST=California/L=San Jose/O=Qboid/OU=TestingWebService/CN=testing.qboid.ai/emailAddress=info@qboid.ai" \
-addext "subjectAltName=DNS:testing.qboid.ai"

Add the self-signed certificate to Perceptor M2

• Download the certificate file (e.g.:self_cert.pem) to the M2 using the M2's Web Browser app, or from a PC over the M2's USB-C port.
• Access the Android Menu entry: Settings -> Security -> Encryption & Credential -> Install from storage
• Select the certificate file (from the downloaded location on the M2)
• Type a value for Certificate Name
• Make sure VPN and apps is selected as Credential use

Testing Server

QBOID provides a testing www server that can be used for experimenting with the different API configurations/protocols.
The test server can be reached through a reverse proxy that's exposing the same service with different combinations of protocols and certificates. All endpoints refer to the same service, so data pushed over https will be visible on the http page and vice versa.

Disclaimer
Before using the server, please review the following:

• The testing server service is provided "as is" without warranty of any kind, either expressed or implied.
• The service is intended to be used only for testing the Perceptor M2 API.
• There is no user or authentication defined, the data pushed to the server will be publicly visible while the test is in progress.
• QBOID reserves the right to modify, suspend or discontinue the testing server service at any time.

List of endpoints

Web Visualization URLs can be opened with any PC or Phone browser. The page will wait for 120s for incoming data sent by any M2 device that's currently using a Testing Server Endpoint.

QR code link to HTTP Web Visualization URL

Device configuration

Testing server endpoints can be configured on the M2 settings in Data Settings -> API Endpoint.
Click on Use Testing Server and select the desired combination of Protocol and certificate.

For using the self-signed certificate:

• Download the certificate : http://testing.qboid.ai:5001/static/self_cert.pem
• Install the certificate using the procedure specified in: Add the self-signed certificate to Perceptor M2

Code examples

Disclaimer: The code is for illustration and learning purposes only. It prioritizes simplicity over production-level robustness and should not be used in a production environment.

Minimal Python app for receiving/parsing a message

Code

from flask import Flask
from flask import request
import json
app = Flask(__name__)

@app.route("/newEntry", methods=['POST'])
def newEntry():
    data = json.loads(request.data)
    print("Barcode: %s Size: %ix%ix%i" % (data["barcode"], data["l"], data["w"], data["h"]))
    return ""

if __name__ == "__main__":
    app.run(host = '0.0.0.0')

Output (2 dimensioning events of the same object)

Barcode: X001SS387V Size: 266x201x72
192.168.7.108 - - [24/Feb/2021 19:34:15] "POST /newEntry HTTP/1.1" 200 -
Barcode: X001SS387V Size: 267x200x72
192.168.7.108 - - [24/Feb/2021 19:36:00] "POST /newEntry HTTP/1.1" 200 -

For testing the previous code set the device endpoint to:

http://[HOST-IP]:5000/newEntry
where [HOST-IP] is the IP address of the PC running the code. E.g.: `192.168.7.100`

Python for generating sample messages

Code

import requests
import json
import random
import string
from datetime import datetime

# To be changed according to the setup
ENDPOINT = 'http://127.0.0.1:5000/newEntry'

def rndString(minsize, maxSize):
    return ''.join(random.choices(string.ascii_uppercase + string.digits, k = random.randint(minsize, maxSize))) 

def createJsonEntry():
    data = {}
    data['timestamp'] = datetime.utcnow().strftime('%Y/%m/%d %H:%M:%S')
    data['l'] = random.randint(10,500)
    data['w'] = random.randint(10,500)
    data['h'] = random.randint(10,500)
    data['weight'] = random.randint(10,50000)
    data['barcode'] = rndString(2,20)
    data['shape'] = 'Irregular' 
    data['device'] = rndString(8,8)
    data['note'] = rndString(0,20)
    attributes = {}
    for i in range(random.randint(0, 4)):
        attributes[rndString(3,5)] = rndString(3,5)
    data['attributes'] = attributes
    strjson = json.dumps(data)
    # Explicitly escaping "/" since python json library is not doing it by default
    strjson = strjson.replace('/', '\/')
    return strjson

if __name__ == "__main__":
    jsonMsg = createJsonEntry()
    print(jsonMsg)
    headers = {'content-type': 'application/json; utf-8', 'Accept' : 'application/json'}
    try:
        response = requests.post(ENDPOINT, data=jsonMsg, headers=headers)
        if (response.ok):
            print('Success')
        else:
            print('Error. Endpoint %s returned code: %i' % (ENDPOINT, response.status_code))    
    except Exception as e:
        print('Error while sending request to endpoint: %s' % ENDPOINT)

Output (Success)

{"timestamp": "2021\/02\/25 05:02:08", "l": 56, "w": 419, "h": 68, "weight": 46405, "barcode": "KPGVETAS", "shape": "Irregular", "device": "Y3S9JH1D", "note": "3RI9CKE2N", "attributes": {"FJ4": "U1HC6"}}
Success

Output (Endpoint returned an error)

{"timestamp": "2021\/02\/25 05:04:52", "l": 494, "w": 430, "h": 290, "weight": 31464, "barcode": "GE7WJ83B3PNJBN", "shape": "Irregular", "device": "DO1KF5ZI", "note": "A3KYJ", "attributes": {"SVRAJ": "HMXK"}}
Error. Endpoint http://127.0.0.1:5000/newEntry returned code: 405

Output (Endpoint unreachable)

{"timestamp": "2021\/02\/25 05:06:08", "l": 449, "w": 129, "h": 432, "weight": 2339, "barcode": "UUYXJ9Y447M", "shape": "Irregular", "device": "BO2X6TD2", "note": "B71U", "attributes": {"AF7Y": "BX44"}}
Error while sending request to endpoint: http://127.0.0.1:5000/newEntry

Python sample app with Authorization check and custom headers

Code

from flask import Flask
from flask import request
import json
app = Flask(__name__)

@app.route("/newEntry", methods=['POST'])
def newEntry():
    print("Authorization: %s" % request.headers.get('Authorization', ""))
    if request.headers.get("Authorization", "") != "qboid":
        return "Authorization error!", 401
    data = json.loads(request.data)
    print("User-Agent: %s" % request.headers.get('User-Agent'))
    print("Headers: %s" % str(dict(request.headers)))
    print("Barcode: %s Size: %ix%ix%i" % (data["barcode"], data["l"], data["w"], data["h"]))
    return ""

if __name__ == "__main__":
    app.run(host = '0.0.0.0')

Output (Success)

Barcode: X001SS387V Size: 266x201x72
192.168.7.108 - - [13/Mar/2023 14:19:57] "POST /newEntry HTTP/1.1" 200 -

Output (Wrong Authorization)

192.168.7.108 - - [13/Mar/2023 14:19:21] "POST /newEntry HTTP/1.1" 401 -

For testing the previous code set the device end point to:

http://[HOST-IP]:5000/newEntry
where [HOST-IP] is the IP address of the PC running the code. E.g.: `192.168.7.100`

And set the Authorization header to:

qboid

Android Intent API

_{Added in 2.3.0}

This is an Android Intent based API where a local application can invoke the QBOID M2 applications and optionally retrieve a dimensioning record.

The API is designed to work with Android Applications following the Android's Intent paradigm, but it also provides equivalent functionalities even to Web Applications running in a common Web Browser.

Intent Definition

QBOID M2 applications can be invoked using an explicit intent with the following parameters:

Optionally, an action and a JSON configuration for that action can be specified in the Extra Bundle

Intent Extra Bundle Structure

Supported actions

dim

M2 applications will be invoked for acquiring a single Dimensioning Record. The workflow will return to the caller once the user confirms/saves the data for the current item. Application settings, upload queue and history won't be accessible until the action is completed or aborted.

Configuration

Intent Returned value

When the caller Activity is resumed, an Intent Result will be returned with a resultCode.

If the user returned to the caller activity without scanning an item (i.e.: Some of the mandatory fields needed for record creation, as indicated by the application configuration, are missing), the returned values would be resultCode = 0 and a null Intent.

If the user correctly scanned an item, the caller will receive a resultCode = -1 and an Intent with the Extra Bundle containing the result of the task.

Returned Extra Bundle Structure

Example of record field in the Extra Bundle

{
  "timestamp": "2022\/10\/05 23:06:45",
  "l": 319,
  "w": 203,
  "h": 421,
  "barcode": "TBA065003602504",
  "shape": "Irregular",
  "device": "FH0402211700146",
  "note": "Comment",
  "attributes": {
    "ovpk": "true",
    "batt": "false",
    "frgl": "true",
    "hazmat": "true"
  },
  "image": "\/sdcard\/qboid\/data\/2022_10_05\/2022_10_05_23_06_15\/Frames\/result_img_1.png",
  "imageseg": "\/sdcard\/qboid\/data\/2022_10_05\/2022_10_05_23_06_15\/Frames\/color0_segmented_1.png",
  "imagecolor": "\/sdcard\/qboid\/data\/2022_10_05\/2022_10_05_23_06_15\/Frames\/color0_1.png"
}

Typical use cases

Following is a description of the most common use cases for the Android Intent API integration and how they can be implemented using the provided API. All these workflows apply to both the Parcel and the Pallet App.

A) Open an M2 Dimensioning App

Scenario
The customer uses several apps and has his own Launcher Application. Once the M2 Dimensioning App is opened, multiple sequences may be collected, settings may be changed, and data offloading can be performed over WiFi using the settings defined in the application.

Implementation
The M2 Dimensioning App will be launched with an Intent with no action and no other Extra defined in the Bundle.

B) Trigger a single dimensioning operation

Scenario
The main workflow is directed by a Third Party app that may require the collection of dimensions, picture and/or other metadata for an item during the workflow. The local Third Party app doesn't require immediate feedback, and there is no hard constraint on when the data needs to be sent over WiFi. Instead, we want to be able to buffer the network requests in case of a slow network or no connection.

Implementation
We want to invoke an intent with action=dim and a config with target=queue (Note: queue is the default value so the config field can be omitted).
The M2 API settings needs to be configured with the correct endpoint.
The endpoint needs to be able to associate the received record to the correct entry in the workflow.

C) Request a dimensioning operation and retrieve the result

Scenario
The main workflow is directed by a Third Party app that may require the collection of dimensions, picture and/or other metadata for an item during the workflow. The app would need to use and/or display the information generated by the M2 Dimensioning App as soon as it regains focus. Additionally, the caller App wants to bypass the default Qboid configuration and keep the acquired sequences away from the standard Upload Queue and History defined in the Qboid app.

Implementation
We want to invoke an intent with action=dim and we need to properly construct the config attribute.

If the caller is an Android app, the target would generally be set to none (or callback if a remote endpoint has to be notified) and the Dimensioning Record would be read from the Intent Returned Value.

If the caller is a Web App, the target has to be set to callback and the proper endpoint should be set to the wanted URL. Generally the endpoint will be defined on the same Web Server that is running the Web Application and would contain the information to identify the current request and/or session. Once the focus is returned to the Web App, it will take care of retrieving the Dimensioning Record for the Web Server.

Usage with an Android Application

This section provides sample code on how to invoke the Explicit Intent, and how to receive the Intent Result for the different typical use cases. Examples are in Java using Activity.onActivityResult. Equivalent code may be written in Kotlin and/or using ActivityResultContracts. Changing the package and class name is sufficient to make it work with the Parcel App or the Pallet App.

A) Open an M2 Dimensioning App
For Invoking the M2 Dimensioning App with no action we can simply define the Explicit Intent and call it with startActivity

// A) Open the M2 Item and Parcel Dimensioning App
Intent intent = new Intent();
ComponentName cName = new ComponentName("ai.qboid.glapp", "ai.qboid.glapp.DimActivity");
// For the Pallet Dimensioning App use:
// ComponentName cName = new ComponentName("ai.qboid.palletsize", "ai.qboid.palletsize.PalletActivity");
intent.setComponent(cName);
context.startActivity(intent);

B) Trigger a single dimensioning operation
An action=dim can be set as Extra simply adding intent.putExtra("action", "dim"); to the previous example

// B) Trigger a single dimensioning operation with the M2 Item and Parcel Dimensioning App
Intent intent = new Intent();
ComponentName cName = new ComponentName("ai.qboid.glapp", "ai.qboid.glapp.DimActivity");
// For the Pallet Dimensioning App use:
// ComponentName cName = new ComponentName("ai.qboid.palletsize", "ai.qboid.palletsize.PalletActivity");
intent.setComponent(cName);
intent.putExtra("action", "dim"); // Select dim as action
context.startActivity(intent);

C) Request a dimensioning operation and retrieve the result
Setting the target=none for the config field can be done using a JSONObject instance.

Additionally, for receiving the result, the M2 Dimensioning Activity needs to be started with startActivityForResult, that will take a requestCode argument to help identify the request that triggered the result being returned.

onActivityResult will be invoked when the called Activity is closed and it will contain the data generated by the M2 Dimensioning App.

// C) Request a dimensioning operation and retrieve the result with the M2 Item and Parcel Dimensioning App
Intent intent = new Intent();
ComponentName cName = new ComponentName("ai.qboid.glapp", "ai.qboid.glapp.DimActivity");
// For the Pallet Dimensioning App use:
// ComponentName cName = new ComponentName("ai.qboid.palletsize", "ai.qboid.palletsize.PalletActivity");
intent.setComponent(cName);
intent.putExtra("action", "dim"); // Select dim as action
// Add config field with target->none to the Intent Extras
JSONObject json = new JSONObject();
try {
    json.put("target", "none");
    intent.putExtra("config", json.toString());
} catch (JSONException e) {}
// Start activity and wait for result
context.startActivityForResult(intent, REQUEST_CODE); // REQUEST_CODE can be any number and it's used to identify the result.

//! Process the result obtained once the called Activity is closed
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE && data != null && resultCode == -1){
        String recordJson = data.getStringExtra("record");
        // -- PROCESS HERE THE DIMENSIONING RECORD --
    }
}

Usage with a Web Application

A Web Application can launch an Android Application with an Intent as described in: Android Intents with Chrome.

The M2 Applications are configured to receive a BROWSABLE Intent with scheme intentapi on their activities.

Below are a few examples on how to invoke the Explicit Intent, and how to receive the Intent Result for the different typical use cases. Examples are provided in Python with Flask + Javascript. Equivalent code may be written in different programming languages and different Web Server. The examples illustrate the usage for the Parcel App, but the same applies to the Pallet App.

A) Open the M2 Item and Parcel Dimensioning App
This use case may be simply implemented adding a link (or a button) pointing to the following URI: intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;end

HTML example:

<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;end">
    A) Open the M2 Item and Parcel Dimensioning App</a>

B) Trigger a single dimensioning operation
The URI from the previous example can be altered using the syntax for defining String extras to configure dim as action: S.action=dim

HTML example:

<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;end">
    B) Trigger a single dimensioning operation</a>

C) Request a dimensioning operation and retrieve the result
Web Applications are unable to receive the Intent Returned value when running in a Web Browser, so a result can be obtained instructing the M2 Dimensioning App on how to send data to the Web Server and then retrieving that information when the Browser Tab is resumed. This workflow can be split in the following steps (diagram):

• Step 1: Web App invokes the M2 Item and Parcel Dimensioning App and configures it to send the result to a remote server

The goal would be to generate an intent URI with a configuration where target=callback and the endpoint is set to a value generated by the current Web Application.

Here is an example of the config JSON string where the server is running at the address http://192.168.1.164:5000 and /callback is the endpoint handling the record coming from M2 Dimensioning App:

{"target":"callback","endpoint":"http://192.168.1.164:5000/callback"}

The config String would then need to be converted to the correct URI encoding using a library like urllib, obtaining something like:

%7B%22target%22%3A%22callback%22%2C%22endpoint%22%3A%22http%3A//192.168.1.164%3A5000/callback%22%7D

The encoded config can then be added to the URI in the previous example prepending it with the attribute: S.config=. The final result would look like:

intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;S.config=%7B%22target%22%3A%22callback%22%2C%22endpoint%22%3A%22http%3A//192.168.1.164%3A5000/callback%22%7D;end

Following is the sample Python + Flask code for generating the URI:

config = '{"target":"callback","endpoint":"%scallback"}' % request.url_root
intent = "intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;S.config=%s;end" % urllib.parse.quote(config)

• Step 2: M2 Dimensioning App sends the result to the Web Server and returns to the Web App

Once the user confirms/saves the data for the current item, the dimensioning record will be sent to the endpoint as defined by the caller. The application would then close and return the focus to the browser running the Web App.

• Step 3: Web app retrieves the result from the remote server once the Browser Tab is resumed

Once the Tab with the Web Application is resumed, the server needs to be queried to retrieve the information sent by the M2 Dimensioning App. This can be done by fetching the data from an endpoint on the server as soon as the Web Document becomes visible again.

Following is a javascript example that detects when document.visibilityState is changed to visible and invokes the update() function that will be implemented to retrieve the information from the server.

<script>
    document.addEventListener("visibilitychange", () => {
        if (document.visibilityState === 'visible')
            update();
    });
    function update() {
       // Query the server for the result
    }
</script>

Web Application use case C) diagram

|

Python code example

We are presenting here an example in Python with Flask + Javascript, summarizing the 3 uses cases discussed before both for the Parcel App and the Pallet App. It includes code to be used in an HTML template and the endpoints to be defined in Flask. We finally provide a fully self-contained Python app.

Disclaimer: The code is for illustration and learning purposes only. It prioritizes simplicity over production-level robustness and should not be used in a production environment.

HTML Template (main.html)

• Provide 3 links as per use cases A), B), and C) for the Parcel App
• Provide 3 links (D), E), and F)) for the Pallet App
• Query the endpoint /size when the Tab is resumed and print the result in a <pre> element.

<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;end">A) (Parcel) Open M2 Dimensioning App</a>
<hr>
<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;end">B) (Parcel) Trigger a single dimensioning operation</a>
<hr>
<a href="{{intent_c}}">C) (Parcel) Request a dimensioning operation and retrieve the result</a>
<hr>
<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;end">D) (Pallet) Open M2 Dimensioning App</a>
<hr>
<a href="intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;S.action=dim;end">E) (Pallet) Trigger a single dimensioning operation</a>
<hr>
<a href="{{intent_f}}">F) (Pallet) Request a dimensioning operation and retrieve the result</a><br>
<pre id="result"></pre>
<script>
    document.addEventListener("visibilitychange", () => {
        if (document.visibilityState === 'visible')
            update();
    });
    function update() {
        var xhttp = new XMLHttpRequest();
        xhttp.open("GET", "size", true);
        xhttp.onload = function () {
            let responseTxt = xhttp.responseText;
            document.getElementById('result').innerHTML = responseTxt;
        };
        xhttp.onerror = function () {
            document.getElementById('result').innerHTML = "Request Error";
        };
        xhttp.send();
    }
</script>

Python Web Server

• Provides a Web Page based on main.html at the endpoint /.
• Receives a response from the M2 Dimensioning App at the endpoint /callback and stores it locally.
• Returns the latest response when queried at the endpoint /size.

latestResponse = "---"

@app.route("/", methods=['GET'])
def main():
    config = '{"target":"callback","endpoint":"%scallback"}' % request.url_root
    intent_c = "intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;S.config=%s;end" % urllib.parse.quote(config)
    intent_f = "intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;S.action=dim;S.config=%s;end" % urllib.parse.quote(config)
    res = render_template("main.html", intent_c = intent_c, intent_f = intent_f)
    return res

@app.route("/callback", methods=['POST'])
def callback():
    global latestResponse
    data = json.dumps(json.loads(request.data), indent = 4)
    latestResponse = data
    return ""

@app.route("/size", methods=['GET'])
def size():
    global latestResponse
    retSize = latestResponse
    latestResponse = "---"
    return retSize

Note: In this example, for simplicity, the case where multiple sessions can be established with the server is not supported. In an actual production implementation the /callback and /size endpoints would require additional variables to properly identify a device and/or session.

Full python code with embedded HTML

from flask import Flask, render_template_string,request,render_template
import json
import urllib.parse
app = Flask(__name__)

main_html = """
<!DOCTYPE html>
<html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
<body>
    
    <h3>Perceptor Android API Test</h3>
    <a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;end">A) (Parcel) Open M2 Dimensioning App</a>
    <hr>
    <a href="intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;end">B) (Parcel) Trigger a single dimensioning operation</a>
    <hr>
    <a href="{{intent_c}}">C) (Parcel) Request a dimensioning operation and retrieve the result</a>
    <hr>
    <a href="intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;end">D) (Pallet) Open M2 Dimensioning App</a>
    <hr>
    <a href="intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;S.action=dim;end">E) (Pallet) Trigger a single dimensioning operation</a>
    <hr>
    <a href="{{intent_f}}">F) (Pallet) Request a dimensioning operation and retrieve the result</a><br>
    <pre id="result"></pre>
    <script>
        document.addEventListener("visibilitychange", () => {
            if (document.visibilityState === 'visible')
                update();
        });
        function update() {
            var xhttp = new XMLHttpRequest();
            xhttp.open("GET", "size", true);
            xhttp.onload = function () {
                let responseTxt = xhttp.responseText;
                document.getElementById('result').innerHTML = responseTxt;
            };
            xhttp.onerror = function () {
                document.getElementById('result').innerHTML = "Request Error";
            };
            xhttp.send();
        }
    </script>
</body>
</html>
"""

latestResponse = "---"

@app.route("/", methods=['GET'])
def main():
    config = '{"target":"callback","endpoint":"%scallback"}' % request.url_root
    intent_c = "intent://#Intent;scheme=intentapi;package=ai.qboid.glapp;S.action=dim;S.config=%s;end" % urllib.parse.quote(config)
    intent_f = "intent://#Intent;scheme=intentapi;package=ai.qboid.palletsize;S.action=dim;S.config=%s;end" % urllib.parse.quote(config)
    res = render_template("main.html", intent_c = intent_c, intent_f = intent_f)
    return res

@app.route("/callback", methods=['POST'])
def callback():
    global latestResponse
    data = json.dumps(json.loads(request.data), indent = 4)
    latestResponse = data
    return ""

@app.route("/size", methods=['GET'])
def size():
    global latestResponse
    retSize = latestResponse
    latestResponse = "---"
    return retSize

if __name__ == "__main__":
    app.run(host = '0.0.0.0')

Testing server

QBOID provides a testing server with http and https endpoints running a live version of the sample Web Application described in this section.

Disclaimer
Before using the server, please review the following:

• The testing server service is provided "as is" without warranty of any kind, either expressed or implied.
• The service is intended to be used only for testing the Perceptor M2 API.
• There is no user or authentication defined; the data pushed to the server may be publicly visible while the test is in progress.
• QBOID reserves the right to modify, suspend or discontinue the testing server service at any time.

Testing Server URLs

Protocol	URL	QR code
HTTP	http://testing.qboid.ai:5001/api
HTTPS	https://testing.qboid.ai:5003/api

Configuration Import/Export

_{Added in 2.5.0}

The purpose of this functionality is to facilitate the export and import of M2 settings, also referred to as preferences, allowing them to be easily applied across multiple devices as well.

Saving Settings/Preferences

To export the configuration of an M2 DImensionig App, the specific button placed under Settings -> Import/Export Settings -> Export settings to local file can be used. Once clicked, this will save the current device configuration to the file /sdcard/qboid/preferences.json, for the Parcel App, and to the file /sdcard/qboid/pallet_preferences.json for the Pallet App.

Loading Settings/Preferences

There are two main workflows to import a previously saved configuration into an M2 device:

1. From local file
   A previously saved preference JSON file can be placed in the proper location. To load it within the M2 application, navigate to Settings -> Import/Export Settings and click the Import settings from local file button.
2. From QR code
   If it is not feasible or desired to move files between devices, QR codes can be used instead. To generate a QR code containing a device configuration, a previously saved JSON file is necessary. Visit the link https://testing.qboid.ai/qr_code_config_generator.html and click on Choose File to select the JSON file that needs to be encoded as a QR code. If the file is a valid configuration, a QR code will be displayed on the webpage. The generated QR code can then be downloaded as a PNG or SVG image. The configuration can be loaded into the M2 device simply scanning the QR code from the main M2 application window or from Settings -> Import/Export Settings.

General warnings

• The QR codes and JSON files are application-specific and only compatible with the app that generated them. For instance, a QR code created using the JSON file exported from the M2 Item and Parcel Dimensioning App cannot be used with the M2 Pallet Dimensioning App.
• A QR code generated with a specific version of the M2 application might not be compatible with a newer version of the application. The M2 application has the capability to verify the compatibility of the scanned configuration with the current application version. In case of incompatibilities, the user is informed, and no changes are applied to the device settings. Each loadable/exportable preference has a defined minimum supported application version, as listed in the Supported settings table. Whenever a preference is modified in a way that is not retro-compatible, its minimum version is updated to a higher value. A JSON file or a QR code are marked as compatible if:
  • No preference has a minimum version, as defined in the M2 application version that exported it, that is higher than the current version of the M2 application.
  • No preference has a minimum version, as defined in the M2 application version that exported it, that is lower than what the current version of the M2 application can support.
• If the JSON file is manually edited incorrectly, the generated QR code might not be properly loadable by the M2 application.

Export/Import Behavior

When exporting to a file or generating a QR code, only the settings that differ from the default values are exported.

The behavior when importing preferences is determined by the restoredefault entry in the JSON:

• If set to true, all preferences NOT defined in the QR code/file will be reset to their default values.
• If set to false, preferences not defined in the QR code/file will remain unchanged.

There is one exception to this rule for the configuration of Attributes (i.e., the 4 soft keys defined on the home screen). This exception will be discussed in more detail in the next section.

Attribute Configuration Exception

Since version 2.6.6, with the introduction of different types for the four attributes on the home screen, more advanced logic has been introduced for exporting and importing attribute configurations to fully support the use case where a QR code is used to reconfigure all attribute entries on the fly.

Here’s how the logic works:

• When exporting an attribute, if any value (key, type, or values) has been changed from the default, the entire configuration of that attribute will be exported, regardless of whether some values are still set to default.

• When importing an older QR code/file (version <2.6.6), if any attribute is modified, the other preferences for that attribute that were not explicitly set will be restored to their default values.

Supported settings

Examples

Restore settings to default

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": true,
  "prefs": []
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": true,
  "prefs": []
}

QR code

Size in Inches with 1/4" precision and weight in lb

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "size_unit",
      "minver": "2.5.0",
      "type": "string",
      "value": "in"
    },
    {
      "key": "size_precision",
      "minver": "2.5.0",
      "type": "string",
      "value": "0.25"
    },
    {
      "key": "weight_unit",
      "minver": "2.5.0",
      "type": "string",
      "value": "lb"
    }
  ]
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "size_unit",
      "minver": "2.5.0",
      "type": "string",
      "value": "in"
    },
    {
      "key": "size_precision",
      "minver": "2.5.0",
      "type": "string",
      "value": "0.25"
    },
    {
      "key": "weight_unit",
      "minver": "2.5.0",
      "type": "string",
      "value": "lb"
    }
  ]
}

QR code

Testing server with auto-upload and all images selected

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "api_endpoint",
      "minver": "2.5.0",
      "type": "string",
      "value": "https:\/\/testing.qboid.ai:5003\/newEntry"
    },
    {
      "key": "api_upload_img_result",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_img_seg",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_img_color",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_results",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    }
  ]
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "api_endpoint",
      "minver": "2.5.0",
      "type": "string",
      "value": "https:\/\/testing.qboid.ai:5003\/newEntry"
    },
    {
      "key": "api_upload_img_result",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_img_seg",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_img_color",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "api_upload_results",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    }
  ]
}

QR code

Set custom attributes

Parcel App

• CASE/EACH
• 3481 with 3 states (undefined, true, false)
• Fragility level: F-1/F-2/F-3

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "attribute1_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "CASE"
    },
    {
      "key": "attribute1_show_values",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "attribute1_values",
      "minver": "2.5.0",
      "type": "string",
      "value": "CASE,0,EACH,0"
    },
    {
      "key": "attribute2_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "3481"
    },
    {
      "key": "attribute2_values",
      "minver": "2.5.0",
      "type": "string",
      "value": ",0,true,1,false,2"
    },
    {
      "key": "attribute3_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "FRAGILITY"
    },
    {
      "key": "attribute3_show_values",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "attribute3_values",
      "minver": "2.5.0",
      "type": "string",
      "value": "F-1,0,F-2,0,F-3,0"
    }
  ]
}

QR code

Pallet App

• CASE/EACH
• 3481 with 3 states (undefined, true, false)
• Fragility level: F-1/F-2/F-3

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "attribute1_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "CASE"
    },
    {
      "key": "attribute1_show_values",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "attribute1_values",
      "minver": "2.5.0",
      "type": "string",
      "value": "CASE,0,EACH,0"
    },
    {
      "key": "attribute2_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "3481"
    },
    {
      "key": "attribute2_values",
      "minver": "2.5.0",
      "type": "string",
      "value": ",0,true,1,false,2"
    },
    {
      "key": "attribute3_key",
      "minver": "2.5.0",
      "type": "string",
      "value": "FRAGILITY"
    },
    {
      "key": "attribute3_show_values",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "attribute3_values",
      "minver": "2.5.0",
      "type": "string",
      "value": "F-1,0,F-2,0,F-3,0"
    }
  ]
}

QR code

Enable 90 days auto-cleanup

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "auto_cleanup_days",
      "minver": "2.5.0",
      "type": "numeric",
      "value": 90
    },
    {
      "key": "auto_cleanup_enabled",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    }
  ]
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "auto_cleanup_days",
      "minver": "2.5.0",
      "type": "numeric",
      "value": 90
    },
    {
      "key": "auto_cleanup_enabled",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    }
  ]
}

QR code

Enable BT Scale

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "btscale_enabled",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    }
  ]
}

QR code

Enable custom field as girth

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "custom_field_enabled",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "custom_field_formula",
      "minver": "2.5.0",
      "type": "string",
      "value": "W,H,+,2,*"
    },
    {
      "key": "custom_field_label",
      "minver": "2.5.0",
      "type": "string",
      "value": "GRH"
    }
  ]
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "custom_field_enabled",
      "minver": "2.5.0",
      "type": "boolean",
      "value": true
    },
    {
      "key": "custom_field_formula",
      "minver": "2.5.0",
      "type": "string",
      "value": "W,H,+,2,*"
    },
    {
      "key": "custom_field_label",
      "minver": "2.5.0",
      "type": "string",
      "value": "GRH"
    }
  ]
}

QR code

Disable QR code cofiguration confirmation

Parcel App

Json Format

{
  "jsonver": 0,
  "app": "parcel",
  "restoredefault": false,
  "prefs": [
    {
      "key": "preferences_import_qr_ask",
      "minver": "2.5.0",
      "type": "boolean",
      "value": false
    }
  ]
}

QR code

Pallet App

Json Format

{
  "jsonver": 0,
  "app": "pallet",
  "restoredefault": false,
  "prefs": [
    {
      "key": "preferences_import_qr_ask",
      "minver": "2.5.0",
      "type": "boolean",
      "value": false
    }
  ]
}

QR code