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
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.
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.
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
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
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
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
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