Working with a Device

As soon as a device is added to an account, a user can fetch information about the 4D Scale – or configure it – using its serial number.

These actions include:

Initiating the calibration process so that the scale and dimensioner can be calibrated

In order to properly calibrate a 4D Scale unit, the base plate should be empty

Initiating the tare process so that the scale readings can be adjusted

Changing user preferences such units of measurement for scale and/or dimensioner

Fetching the last measurements recorded in the cloud

Resetting specific or all user preferences back to the factory defaults

Restarting or shutting down the 4D Scale unit remotely

Please note that the API does not provide a mechanism to start a device remotely after it has been shut down.

If a device is “public” it can be controlled via the API without restrictions. However, “private” devices may only be controlled if authorized with the proper account API key.

Fetch information about device

Information about a device can be fetched by calling GET /devices/{serialNumber}

The resulting Device object contains information such as:

  • Whether or not the device is currently connected to the cloud
  • When it was “first seen” (registered with the cloud) and “last seen” (last connected to the cloud), in UTC timestamps

Each device contains DeviceMeta information such as:

  • The serial number of the unit
  • Title and version of the on-board application
  • Low-level details about hardware components

Initiate Calibration process

The calibration process should be initiated in situations such as:

  • When a device is first set up
  • When device calibration settings are reset
  • When measurements are deemed problematic or incorrect

Calling POST /devices/{serialNumber}/calibrate will initiate the process on the remote device.

Please note that the API call will return before the calibration process completes.

If your application should track exactly when the calibration process begins and ends, you can use the Real-time API.

Initiate Tare process

The tare process should be initiated in situations such as:

  • When a device is first set up and calibrated
  • When the contents of a package (container) should be weighed without the weight of the container itself
  • When weight measurements are deemed problematic or incorrect

Calling POST /devices/{serialNumber}/tare will initiate the process on the remote device.

Please note that the API call will return before the tare process completes.

If your application should track exactly when the tare process begins and ends, you can use the Real-time API.

Change preferred units of measurement

It is possible to customize the units of measurement by calling the following endpoints:

Scale

PATCH /devices/{serialNumber}/preferences/weight-unit where the unit query parameter may be one of: Kilograms Grams Pounds Ounces

Dimensioner

PATCH /devices/{serialNumber}/preferences/dimensions-unit where the unit query parameter may be one of: Centimeters Inches

The preference is persisted locally, on the 4D Scale unit. This means that the user interface of the on-board application will also use this preference.

Fetch last recorded measurements

A successful 4D Scale API integration requires that the real world measurements of the scale and dimensioner be captured and used in the integrated application.

This data is referred to as device state.

The last recorded measurements can be obtained by calling GET /devices/{serialNumber}/last-state

Please note that in order to obtain the device state, the 4D Scale must be active and connected to the cloud. If the 4D Scale is offline or has connection issues, this endpoint will return an error.

The resulting ScaleState object contain information such as:

  • The scale reading, in the preferred unit of measurement
  • The tare in use, in the preferred unit of measurement
  • A timestamp of the reading, in UTC
  • An indicator of whether or not the scale has encountered an error, and if so, details about the incident
Please note that the Weight reading is net. The tare value has already been subtracted from the gross weight reading.

The resulting DimensionerState object contain information such as:

  • The dimension reading, in the preferred unit of measurement
  • A timestamp of the reading, in UTC
  • An indicator of whether or not the dimensioner has encountered an error, and if so, details about the incident
Please note that the Dimensions data structure contains X Y Z properties.

These map to Length Width Height respectively.

Fetch information about real-time subscribers (receivers)

Context is a key part of user experience. It is possible to fetch information about receivers listening for real-time updates by a given device by calling GET /devices​/{serialNumber}​/receivers

Details in each ReceiverMeta object include the product title and version of the client application, the platform (such as web, mobile or desktop), and the unique “fingerprint” of the machine running the receiver application.

Reset preferences for a device

A 4D Scale device can be reset to factory defaults on several levels (or a combination of these):

  • Clearing team/account assignment
  • Clearing hardware calibration data
  • Resetting user preferences such as units of measurement

Resetting a device to factory defaults can be done by calling POST /devices/{serialNumber}/reset and providing a body request consisting of an array of ResetOptions which may be one or more of: Team HardwareCalibration UserPreferences

Note that clearing the hardware calibration data will require that the 4D Scale be recalibrated before it can be used again.

Power cycle (restart) or shut down a device remotely

A 4D Scale device that is connected to the Internet can be restarted or shut down remotely.

This can be done by calling POST /devices/{serialNumber}/power where the powerLevel query parameter may be one of: RestartApp RestartDevice ShutdownDevice

Please note that the API does not provide a mechanism to start a device remotely after it has been shut down.

Was this article helpful?

Yes No

Related Articles