Scale Integrations

RocketShipIt comes with the RocketShipIt Scale Server which allows you to interact with a shipping scale programatically via an HTTPS REST JSON API.

Note: The RocketShipIt Scale Server is Beta software. Your scale may not yet be supported.

The server is HTTPS only. The default certificate is self-signed. key.pem and cert.pem files will be created in the same directory as the executable on server start if they do not exist. If you need "valid" localhost certificates see: mkcert. You can replace key.pem and cert.pem with your own certificates.

API Routes

GET /scale Get a list of attached supported scales. Make sure your scale is powered on!

GET /hid Get a list of attached Human Interface Devices for debugging/connecting

GET /shutdown Shutdown the server

GET /scale/read/raw/:vendor_id/:product_id/:bytes Read raw bytes from device given vendor/product ID and the number of bytes to read.

Example response:

{
    "bytes_str": "[3 2 11 255 0 0 0]",
    "bytes": "AwIL/wAAAA=="
}

You can get the vendor_id and product_id from /hid if your device is unsupported or /scale if your scale is officially supported.

Serial or Serial/USB routes

It is our goal to support all possible shipping scales; however, we cannot afford to purchase and test all scales.

Most shipping commercial shipping scales communicate over serial or virtual serial communication over USB. If your shipping scale communicates in this way these routes will allow you to communicate with your shipping scale. Unfortunatly, there is no standard communication method. All scales communicate differently. At this time it will be up to you to figure out how your scale communicates; however, these routes should provide everything you need to get started.

POST /serial/open Open a serial/USB-serial device by name

Example request:

{
    "name": "COM3,
    "baud": 9600,
    "read_timeout_milliseconds: 5000
}

POST /serial/write Write bytes (encoded as base64) to serial port by name

Example request:

{
    "name": "/dev/pts/4",
    "bytes": "AwIL/wAAAA=="
}

POST /serial/read Read num_bytes and block until bytes are read or read_timeout_milliseconds occurs first.

Example request:

{
    "name": "/dev/pts/4",
    "num_bytes": 9
}

Example Response:

{
    "bytes": "AwIL/wAAAA=="
}

POST /serial/close close port by name

Example request:

{
    "name": "/dev/pts/4"
}

Reference

Common bytes to write

These are common bytes used to initialze the scale or request a weight.

ASCII	Base16	Base64
"W\r\n"	570D0A	"Vw0K"
"\r"	0D	"DQ=="
"W\r"	570D	"Vw0="
"\rW\r"	0D570D	"DVcN"
"\r\r"	0D0D	"DQ0="

Troubleshooting

Depending on your OS, you may need to start the server with admin or elevated privileges to read/write bytes to your USB/scale device.

If you get hidapi: failed to open device there is a good chance you don't have appropriate privileges to read your scale.

Mocking and Testing

The RocketShipIt Scale Server provides a mock serial device named test.

• /serial/open with the name test will always succeed.
• /serial/write with name test will always succeed and return status code 200.
• /serial/read with name test will always return:

    {
        "name": "test",
        "bytes": "dGVzDA=="
    }

Supported Scales

Nearly all scales should be supported by the RocketShipIt Scale Server. If you are having trouble connecting your scale please reach out to RocketShipIt support. If you send us your scale we will do our best to make it work and send it back. This process usually only takes a few days.

Physically Tested

These scales have been physically tested by RocketShipIt and known to work:

• Fairbanks Scales SCB-R9000 (recommended for most shippers)
• DYMO Digital Postal Scale M25-US

Should work

These scales are known to work as reported by other RocketShipIt customers:

• Fairbanks Scales SCB-R9000
• Dymo-CoStar Corp. M25 Digital Postal Scale
• Stamps.com Model 510 5LB Scale
• Stamps.com Scale
• USPS (Elane) PS311 (XM Elane Elane UParcel 30lb)
• Stamps.com Stainless Steel 5 lb. Digital Scale
• Stamps.com Stainless Steel 35 lb. Digital Scale
• Mettler Toledo
• SANFORD Dymo 10 lb USB Postal Scale
• DYMO Digital Postal Scale
• Postal Scale
• Brecknell PS-USB

Communicating with a HID scale

For this tutorial we will show you the process of communicating with a Fairbanks Scales SCB-R9000 HID scale.

Launch the RocketShipIt Scale Server from the cmd/terminal: rs-scaleserver.exe

A browser window should open, if not navigate to https://localhost:8084. By default this will be a self-signed cert. You should see a minimal site with a link to this documentation. If you need "valid" localhost certificates see: mkcert. You can replace key.pem and cert.pem with your own certificates.

Next, navigate to https://localhost:8084/hid. This should show a list of compatible HID devices. This list may include your mouse, keyboard, or other HID devices not related to your scale. The list should show a manufactor and product description but might not be available on all systems. If you cannot find your device by the description you may need to unplug the device, refresh https://localhost:8084/hid, make note of the current devices, plug in device, and refresh again to find your device.

My system didn't show the scale's Manufacturer or Product description so I had to infer it by unplugging and plugging it back in:

[
    {
        "Path": "0002:0024:00",
        "VendorID": 2919,
        "ProductID": 21854,
        "Release": 4,
        "Serial": "",
        "Manufacturer": "",
        "Product": "",
        "UsagePage": 0,
        "Usage": 0,
        "Interface": 0
    },
...

The next step is to plug in the VendorID and ProductID for your scale into a URI which reads raw bytes for the scale. The VendorID is 2919 and the ProductID is 21854. The URI format to read raw bytes from a scale is /scale/read/raw/:vendor_id/:product_id/:bytes. We can read 10 bytes from this particular scale by doing a GET request to https://localhost:8084/scale/read/raw/2919/21854/10

Any value recieved is a success, especially if it changes when you add weight and refresh. It is now up to you to figure out how your scale represents the weight in raw bytes. Here are a few common scenarios you should run on your scale. The first thing you should look for is a change in bytes when you add some weight to your scale. Then:

• Centered value with zero weight
• < 1 lb
• >= 1lb
• Non-centered
• Negative weight (use the zero/tare function/button)
• Change weight units

A centered value of 0lbs gives:

{
  "bytes_str": "[3 4 12 254 0 0 0 0 0 0]",
  "bytes": "AwQM/gAAAAAAAA=="
}

.35lbs gives:

Notice this is almost identical to the output above except our weight is being represented as 35 instead of 0. We have weight being represented. Because we know the weight is .35 it actually corresponds quite nicely as we see 35 in the 5th byte position. This is almost certainly the byte position where weight is represented.

{
  "bytes_str": "[3 4 12 254 35 0 0 0 0 0]",
  "bytes": "AwQM/iMAAAAAAA=="
}

3.40lbs gives:

Hmm, ok it looks like once we have over 256 it overflows to the next position. But, what does that mean? I'm going to guess that it's a count for the number of times it overflows. Let's see: (256 * 1) + 84 = 340. That looks right. Let's try another weight.

{
  "bytes_str": "[3 4 12 254 84 1 0 0 0 0]",
  "bytes": "AwQM/lQBAAAAAA=="
}

45.90 gives:

Counting the overflow seems to work (17 * 256) + 238 = 4590. 4590/100 = 45.90 Bingo! We now know how to convert the scale's raw bytes to lbs!

{
  "bytes_str": "[3 4 12 254 238 17 0 0 0 0]",
  "bytes": "AwQM/vMRAAAAAA=="
}

-.35lbs gives:

The second position is changing when the scale is negative.

{
  "bytes_str": "[3 5 12 254 221 255 0 0 0 0]",
  "bytes": "AwUM/t3/AAAAAA=="
}

.16kg gives:

It looks like the third position indicates if the scale is returning kg or lbs.

{
  "bytes_str": "[3 4 3 254 16 0 0 0 0 0]",
  "bytes": "AwQD/hAAAAAAAA=="
}