Tricolops Dimensioning Application Integration Guide

The most up to date integration guide can be found here, for help integrating with the dimensioning application, please contact support@tricolopstechnology.ca.

This guide outlines different methods to obtain dimensions from Tricolops Dimensioning application, allowing you to print shipping labels directly from a barcode scan. The Tricolops Dimensioning application can be downloaded here. Follow this guide to setup the Tricolops Dimensioning application.
A scale or Tricolops dimensioner connection is not required for testing, the application will simply respond with 0 values if the scale or dimensioner is not connected.

There are 2 ways to get dimensions from the Tricolops Dimensioning application:

  • TCP/IP socket

  • Webserver / RESTful API

TCP/IP

It is recommended to use TCP/IP method if you are using a Windows or Linux Desktop application.

  • With the Tricolops Dimensioning application running, the application will listen to port 59086 on localhost (127.0.0.1)

  • Once communication is established, the program will respond to the following ASCII character commands:

    Character

    Key sequences sent

    A

    Ctrl A, used to highlight all characters in a text field

    B

    Backspace, used to remove characters in a text field if Ctrl-A is not available.

    E

    Enter, used to submitting a form.

    S

    Space

    T

    Tab, used to switch from one text field to the next

    l

    Length of the package rounded (without decimal places)

    L

    Length of the package (with decimal places)

    w

    Width of the package rounded (without decimal places)

    W

    Width of the package (with decimal places)

    h

    Height of the package rounded (without decimal places)

    H

    Height of the package (with decimal places)

    m

    Weight of the package rounded (without decimal places)

    M

    Weight of the package (with decimal places)


    Additionally, the keystrokes can be customized based on the name of the window. The following table demonstrate some examples:

     

    Sequence

    Behaviour

    ALTWTHTM

                                     

    Highlights the current textbox, then sends exact length, width, height, and weight on all windows

    AMTLTWTH

    Highlights the current textbox, then sends the exact weight, length, width, and height on all windows

    MTTTlTwTh

    Inputs the exact weight, tabs three times, then sends rounded length, width, and height on all windows (For UPS WorldShip)

    ups,MTTTlTwTh, netparcel,ALTWTHTM, AlTwThTM

    Sends keystrokes MTTTlTwTh into all windows containing the name ups Sends keystrokes ALTWTHTMinto all windowscontaining the name netparcel

    Sends keystrokes AlTwThTM into all other window



    Communicate Using TCP/IP

    It is recommended to use TCP/IP integration method if you are using a Windows or Linux Desktop application to communicate with the Tricolops Dimensioner.

    1.    The application will listen to TCP port 59086 on localhost (127.0.0.1) while it is running.

         2.    Once TCP communication is established, the program will respond to the following ASCII character commands:

    Command

    Function

    Example reply

    D

    Dimensions of the object in millimeters (dimensions are always in mm)

    0.0 0.0 0.0 (if no object detected / camera not connected)

    12.3 13.3 14.3 (object detected)

    d

    Dimensions of the object (as displayed)

    0.0 0.0 0.0 (if no object detected / camera not connected)

    12.3 13.3 14.3 (object detected)

    W

    Weight captured by the scale in kg (weight is always in kg)

    0.41

    w

    Weight of the object (as displayed)

    0.41

    V

    Application version

    1.5.0

    S

    Serial number of the dimensioner

    17122430000

    s

    Dimensioner status

    Place objects in trigger area

    T

    Send test dimensions (Can be used without a dimensioner connected)

    1.23 12.3 123.0

    Q

    Terminate communication (the communication socket will be closed)

    N/A

    K

    Terminate Tricolops Dimensioning App (the communication socket will be closed and Tricolops Dimensioning App will exit)

    N/A

       Sample Screenshot

       

Communicate Using RESTful API

It is recommended to use the RESTful API integration method if you are using a web application to communicate with the Tricolops Dimensioner

1.    The application will listen to HTTP port 8080 on localhost (127.0.0.1) while it is running.

  The port can be configured by going to

Advanced Settings Advanced Webserver Port

2.    The API end point is http://127.0.0.1:8080/data, assuming the webserver port is not changed. For Chrome, Microsoft Edge, and other Chromium based browers, the flag chrome://flags/#block-insecure-private-network-requests needs to be disabled.

3.    Sample data

NOTE: dimensions are always in mm, weight is always in kilograms

  • {
      "length": "388.113037",
      "width": "321.346466",
      "height": "689.845215",
      "weight": "11.920000",
      "status": "7",
      "message": "Object detected"
    }
    { "length": "0.000000", "width": "0.000000", "height": "0.000000", "weight": "0.000000", "status": "0", "message": "Device not connected"
    }
  • List of status and codes:
    StatusState
    0INIT – Application is running, but no dimensioner is connected
    1CONNECTING – Application is attempting to connect to a dimensioner
    2REQUIRE_SETUP – Additional setup is required (setting dimension area)
    3CONNECTED – Application has successfully connected to the dimensioner
    4WARMUP – Dimensioner is warming up
    5NOT_READY – Dimension area is not flat / not perpendicular to surface
    6READY – Dimensioner is dimensioning packages but no package is detected in dimension area
    7DIMENSIONING – Package is detected in dimension area, if package is dimensioned successfully, length, width, and height will be non-zero. If the package cannot be dimensioned (out of field of view, too reflective, or dark), length, width, and height will be zero.
    Messages
    Messages are important when status is 7 – DIMENSIONING, the list of possible messages and their interpretations are:

    Message

    Explanation

    Object is not fully in view

    The package is not fully in the view of the camera, possible scenarios are:

             The operator is scanning a barcode on the box and their hand / barcode scanneris in the way.If “Keep History” in Advanced

    -> Settings is turned on, the measurements will be the last successful measurement of the box, otherwise, the measurements will be all zeros.

             The package needs to be re-positioned to be fully in the view of the camera, the measurements will be all zeros.

             The package is too large to be measured, the measurements will be all zeros.

    Object measurement is not stable

    The measurements are not stable, possible scenarios are:

              The package is shiny or has lots of fine features

              The package is still moving

    The measurements may not be accurate.

    Object is not a cuboid

    The object is not a cuboid.

    If “Display Non-cuboid Parcel” in Advanced -> Settings is turned on, and the package failed cuboid test parameters, this message will be displayed. The measurements will be the smallest hexahedron within which the object can be contained.

    Object is oversized

    If “Display Oversized Parcel” in Advanced -> Settings is turned on, and the package larger than the maximum dimensions, this message will be displayed. The measurements will be the object's dimensions.

    Object cannot be measured

    The object cannot be measured for other reasons. The measurements will be all zeros.

    Object measured successfully

    The measurements will be the object's dimensions.



                  Sample JavaScript code

    With the Tricolops Dimensioning Application running, sample JavaScript code can be found by going to http://127.0.0.1:8080 (port can be customized in Advanced Settings

    – Advanced – Webserver port). Once webpage is displayed, right click on the web page and select View Source or View Page Source. Contact support@tricolopstechnology.ca to request a standalone HTML page with sample JavaScript code to communicate with the dimensioning application.

     

    The same code can be found on https://content.tricolopstechnology.ca/resources/home.html, navigating to this URL will display camera images and dimensions when the Tricolops Dimensioning Application


    is running on the target computer. For Chrome, Microsoft Edge, and other Chromium based browsers, chrome://flags/#block-insecure-private-network-requests needs to be disabled.

    Acquiring Images Using RESTful API

    With the Tricolops app running, you can access the JPEG images captured by the dimensioner through issuing GET request to http://127.0.0.1:8080/video.

    High definition video images can be captured by dimensioners shipped after January 1st, 2019. To enable high definition video image, go to Advanced Settings Advanced, and enable “HD Video”.

    If you would like the images labelled, the following URL will return images labelled according to parameters:

    URL Parameter

    Result

    box=true

    The outline of the parcel will be drawn on the image

    dimension=true

    The dimensions of the parcel will be printed on the image

    weight=true

    The weight of the parcel will be printed on the image

    area=true

    The trigger area will be outlined on the image

    For example:

    http://127.0.0.1:8080/video?box=true&dimension=true&weight=true will return an image with the outline of the box, as well as dimensions and weight of the box printed at the bottom of the image.

    Acquiring History Data Using RESTful API

    With the Tricolops app running, you can access the history and images captured by the Tricolops History application through issuing POST request to http://127.0.0.1:8080/history.

    Input Parameters

     

    Parameter

    Description

    start

    Integer, Number of milliseconds since Epoch. If this parameter is specified and greater than 0, only entries saved at or after start” time will be returned.

    end

    Integer, Number of milliseconds since Epoch. If this parameter is specified and greater than 0, only entries saved at or before end time will be returned.

    offset

    Integer, If this parameter is specified and greater than 0, the first offset rows are excluded from the returned result.

    count

    Integer, If this parameter is specified and greater than 0, the number of rows returned is limited to count rows, otherwise number of rows returned is limited to 250 rows.

    barcode

    String, If this parameter is specified and not empty, only entries with barcode matching barcode is returned.

    exact_barcode

    Boolean, If this parameter is specified and set to True, only entries with barcode that match “barcode” exactly is returned, otherwise all entries with barcodes that is like barcode will be returned.

    quantity

    Integer, If this parameter is specified and greater than 0, only entries with quantity equal to quantity will be returned.

    company

    String, If this parameter is specified and not empty, only entries with company matching company will be returned.


    Output Parameters

    The returned results are arrays of objects that represents each row in the Tricolops History table. The parameters of each object represent the column names, they are:

    Parameter

    Description

    barcode

    String, the barcode associated with the entry.

    timestamp

    Integer, number of milliseconds since Epoch that the entry is captured.

    company

    String, the company associated with the entry.

    quantity

    Integer, the quantity associated with the entry.

    weight

    Integer, the weight associated with the entry.

    length

    Integer, the length associated with the entry.

    width

    Integer, the width associated with the entry.

    height

    Integer, the height associated with the entry.

    video_uri

    String, the relative path for the captured image. This path is dynamically generated every time a POST request to /history is issued. Once a POST request to /history is issued, all past video_uri are invalidated.


    Example Input

    Empty JSON object

    {

    }

     

    Example Output

    Up to 250 entries are returned.

    [{

    "barcode": "fc049b4d-fc84-4457-92a4-fdf5f76f8b86", "company": "",

    "height": 10.199999962002039,

    "length": 27.399999897927046,

    "quantity": 1,

    "timestamp": 1559243584285, "video_uri": "/history/video/0", "weight": 0.0,

    "width": 25.399999905377626

    }, {

    "barcode": "b5bb1e84-32e6-4a0c-9556-b3ffbb16d9fd", "company": "",

    "height": 10.799999959766865,

    "length": 27.199999898672104,

    "quantity": 1,

    "timestamp": 1559243580204, "video_uri": "/history/video/1", "weight": 0.0,

    "width": 25.399999905377626

    }]

     

    Example Input 2

    Return all entries after 5/30/2019, 3:13:00 PM GMT, skip the first 200 entries and limit the number of returned entries to 200.

    {

    "start": 1559243580204,

    "offset": 200,

    "count": 200

    }

     

    Example Input 3

    Return entry that matches the specified barcode exactly.

    {

    "barcode": "b5bb1e84-32e6-4a0c-9556-b3ffbb16d9fd", "exact_barcode": true,

    "count": 1

    }

     

    Example Input 4

    Return entries that matches parts of the specified barcode.

    {

    "barcode": "b5bb1e84-"


    }



Need more info?

This documentation page has been extracted from the Q&A section where you can discuss it and get feedback.
Related question