Scale Integration¶

Module Not Currently Installed

As of the 2026-04-12 module audit, sr_scale is NOT installed in production (sr_live_jan19_backup on EXP). The module exists on disk but has never been activated.

Weight capture that IS live today is manual entry on the customer_pickups.actual_weight and box_details.actual_weight fields (part of sr_management). 26,592 of 31,395 production pickups have weight values captured this way.

sr_scale would add direct serial/USB scale integration on top of that manual workflow — but it's pending a decision about whether scales are actually wired up to workstations. Do not rely on this page as operational documentation until Dan approves installation.

See the developer changelog 2026-04-12 entry for full context.

Last Updated: March 2026 (content) / April 2026 (status banner added) Status: NOT INSTALLED — documentation retained for reference

The Scale Integration module (sr_scale) connects industrial scales to Odoo via serial/USB ports so that weight readings flow directly into the system. It is used by warehouse operators (weighing incoming material), yard staff (capturing pickup weights), and managers (reviewing weight history and configuring devices).

What the Scale Module Does¶

The module provides three capabilities:

Device configuration -- register each physical scale with its serial port settings, communication protocol, unit of measure, and weight validation range
Interactive weighing -- a popup wizard that lets operators read a scale, capture tare, and save the net weight with a reference and notes
Reading history -- a timestamped log of every weight reading, searchable by device, date, user, and reference

The module depends on the base and stock apps (for warehouse location linking) and requires the pyserial Python library for serial port communication.

From the Odoo main menu:

Scales
  |-- Configuration
  |     |-- Scale Devices
  |
  |-- Operations
        |-- Weigh Item
        |-- Reading History

Menu Item	What It Opens
Scale Devices	List and form views for configuring each physical scale (serial port, protocol, validation)
Weigh Item	The weighing wizard -- a popup form to read weight, tare, and save a reading
Reading History	A chronological list of all saved weight readings across all devices

Scale Devices -- Configuration¶

Navigate to Scales > Configuration > Scale Devices to see all configured scales. Each device record stores the full serial communication profile and weight parsing rules.

Identity and Location Fields¶

Field	What It Means	Example
Name	A descriptive label for the scale. Required.	"Floor Scale 1", "Platform Scale - Dock"
Active	Whether the device appears in normal views. Uncheck to archive.	True
Warehouse	The `stock.warehouse` where this scale is physically located.	"Sunbright Warehouse"
Status	Current connection state, shown as a color-coded badge.	Disconnected, Connected, Error
Error Message	If the status is Error, the last error detail is shown here. Read-only.	"Serial port error on /dev/ttyUSB0: ..."

Connection Settings¶

These fields control how Odoo talks to the scale over the serial port.

Field	What It Means	Example
Serial Port	The OS device path for the serial/USB connection. Required.	`/dev/ttyUSB0`, `/dev/ttyS0`, `COM3`
Baud Rate	Data transmission speed. Must match the scale's configuration.	9600 (most common)
Data Bits	Number of data bits per byte.	8 (default) or 7
Parity	Error-checking scheme.	None, Even, or Odd
Stop Bits	Number of stop bits per byte.	1 (default) or 2
Timeout (seconds)	How long Odoo waits for a response before giving up.	2.0

Finding the Serial Port Path

On Linux, USB-to-serial adapters typically appear as /dev/ttyUSB0, /dev/ttyUSB1, etc. Built-in serial ports appear as /dev/ttyS0, /dev/ttyS1. You can list available ports by running ls /dev/tty* on the server. The Odoo service user must have read/write permission on the port (typically by being in the dialout group).

Protocol Settings¶

The protocol tells Odoo how to communicate with the scale -- some scales broadcast weight continuously, while others require a command before they respond.

Field	What It Means	Example
Protocol	The communication pattern the scale uses. Required.	Continuous Output, Command/Response, MT-SICS, Custom
Command String	The command to send to the scale before reading. Only used with Command/Response, MT-SICS, and Custom protocols. Supports escape sequences.	`W\r\n`, `S\r\n`
Weight Regex	A regular expression used to extract the numeric weight from the raw serial response.	`([+-]?\d+\.?\d*)` (default)
Unit of Measure	The weight unit the scale reports in.	Pounds (lb), Kilograms (kg), Ounces (oz), Grams (g)

Protocol Types Explained¶

Protocol	How It Works	When to Use
Continuous Output	The scale continuously streams weight data. Odoo opens the port and reads the next line. No command is sent.	Scales that broadcast weight automatically (most simple floor scales)
Command/Response	Odoo sends a command string, then reads the scale's reply.	Scales that only report weight when asked (e.g., send `W\r\n` to get weight)
MT-SICS	Mettler Toledo Standard Interface Command Set. Odoo sends the configured command (typically `S\r\n`) and parses the SICS response format.	Mettler Toledo scales using the SICS protocol
Custom	Same as Command/Response, but intended for non-standard protocols where you provide both the command and a custom regex pattern.	Scales with unusual output formats

Weight Regex

The default regex ([+-]?\d+\.?\d*) captures a signed or unsigned decimal number from the serial output. If your scale sends output like ST,GS,+ 150.5 lb, this regex will extract 150.5. For scales with unusual formatting, you may need a custom pattern. The regex must contain at least one capture group -- the first capture group is used as the weight value.

Weight Validation¶

Field	What It Means	Example
Default Tare Weight	Container weight subtracted from gross readings by default.	0.0
Minimum Valid Weight	Readings below this value are rejected as invalid.	0.0
Maximum Valid Weight	Readings above this value are rejected as invalid.	10000.0

Validation Range

When the scale returns a weight outside the min/max range, Odoo raises an error and does not save the reading. Set these values to match the realistic operating range of the scale. For example, if a floor scale is rated for 5,000 lb, set the maximum to 5000 to catch erroneous readings early.

Last Reading (Read-Only)¶

Field	What It Means	Example
Last Reading	The most recent weight value captured from this device.	342.5
Last Reading Date	When the last reading was taken.	2026-03-03 14:22:00
Readings (stat button)	Total number of readings recorded for this device. Click to view the full list.	87

Device Actions¶

The device form has two action buttons in the header bar:

Test Connection¶

Open a scale device record
Click Test Connection (plug icon) in the header
Odoo opens the serial port, reads one weight value, and parses it
On success: status changes to Connected, a green notification shows the weight, and Last Reading is updated
On failure: status changes to Error, the error message is saved, and a popup explains what went wrong

Read Weight¶

Open a scale device record
Click Read Weight (balance icon) in the header
Odoo reads the current weight from the scale
The weight is validated against the min/max range
On success: Last Reading and Last Reading Date are updated, the device status stays Connected
On failure: the device status changes to Error and a descriptive error is shown

Troubleshooting Connection Failures

If Test Connection fails, check these common causes:

Port path wrong -- verify the path with ls /dev/ttyUSB* on the server
Scale not powered on -- the serial port will open but no data arrives
Baud rate mismatch -- the most common serial configuration issue; check the scale's manual
Permission denied -- the Odoo service user needs access to the serial port (add to the dialout group on Linux)
pyserial not installed -- install it with /opt/odoo17/odoo17-venv/bin/pip install pyserial

Weighing Wizard -- Weigh Item¶

Navigate to Scales > Operations > Weigh Item to open the interactive weighing wizard. This is the primary tool operators use for day-to-day weighing.

The wizard opens as a popup dialog with the following fields and buttons:

Wizard Fields¶

Field	What It Means	Example
Scale Device	The scale to read from. Only devices with status "Connected" appear in the dropdown.	"Floor Scale 1"
Auto Refresh	When enabled, the wizard can poll the scale automatically.	True / False
Current Weight	The last weight read from the scale. Read-only, displayed in large bold text.	342.5
Tare Weight	The container or packaging weight to subtract. Can be entered manually or captured with the Tare button.	12.0
Net Weight	Automatically calculated: Current Weight minus Tare Weight. Displayed in large bold text.	330.5
Reference	An optional identifier to link this reading to another record -- a pickup ID, box barcode, or work order number.	"PU-2026-0142"
Notes	Free-text notes about the reading.	"Aluminum cans, wet"

Wizard Buttons¶

Button	What It Does
Read	Reads the current weight from the selected scale and updates Current Weight. The wizard stays open so you can read multiple times.
Tare	Reads the current weight and sets it as the Tare Weight. Use this with an empty container on the scale to capture the container weight, then load the material and click Read for the gross weight.
Save Reading	Creates a permanent `sr.scale.reading` record with the gross weight, tare weight, reference, and notes. Shows a success notification with the net weight, then closes the wizard.
Close	Closes the wizard without saving.

Typical Weighing Workflow¶

Navigate to Scales > Operations > Weigh Item
Select the scale device from the dropdown
Place the empty container on the scale
Click Tare -- the container weight is captured as the tare
Load the material into the container
Click Read -- the gross weight appears, and net weight is calculated automatically
Enter a Reference (pickup ID, box barcode, etc.) and any Notes
Click Save Reading -- the reading is saved and a confirmation notification appears

Re-reading Before Saving

You can click Read as many times as needed before saving. Only the final weight at the time you click Save Reading is recorded. This is useful if the scale is still settling or you need to adjust the load.

Reading History¶

Navigate to Scales > Operations > Reading History to see all saved weight readings. Readings are displayed newest-first.

Reading Fields¶

Field	What It Means	Example
Timestamp	Date and time the reading was taken. Defaults to the moment the record is created.	2026-03-03 14:22:00
Scale Device	Which scale produced this reading.	"Floor Scale 1"
Gross Weight	The total weight read from the scale (before tare).	342.5
Tare Weight	The container/packaging weight that was subtracted.	12.0
Net Weight	Calculated automatically: Gross Weight minus Tare Weight. Displayed in bold in the list.	330.5
Unit of Measure	Pulled from the device configuration. Read-only.	lb
Reference	The optional reference entered during weighing.	"PU-2026-0142"
Reading Type	How the reading was captured.	Manual Read, Automatic, Tare Capture
User	The Odoo user who took the reading.	"Admin"
Raw Data	The raw serial string received from the scale (hidden by default in the list view).	"ST,GS,+ 342.5 lb"
Notes	Any notes entered during the reading.	"Aluminum cans, wet"

Reading Types¶

Type	Meaning
Manual Read	Weight was captured through the wizard or a manual device read. This is the default.
Automatic	Weight was captured by an automated process.
Tare Capture	A tare weight reading.

Search and Filters¶

The Reading History view includes built-in filters and groupings:

Quick Filters:

Filter	What It Shows
Today	Readings from today only
This Week	Readings from Monday through today
This Month	Readings from the 1st of the current month
Manual	Only Manual Read type
Automatic	Only Automatic type
Tare	Only Tare Capture type

Group By Options:

Group By	Organizes Readings By
Device	Which scale produced the reading
Date	Day the reading was taken
User	Who took the reading
Reading Type	Manual, Automatic, or Tare

Search Fields:

You can type into the search bar to search across Device, Reference, User, and Notes.

Accessing Readings from a Device¶

You can also view readings for a specific scale device:

Open Scales > Configuration > Scale Devices
Open a device record
Click the Readings stat button in the top-right corner
The Reading History list opens, pre-filtered to that device

Security and Access¶

The module defines two security groups under the "Scale Integration" category:

Group	Scale Devices	Scale Readings	Weighing Wizard	Who Should Have It
Scale User	Read only	Read + Create	Full access	Warehouse operators, yard staff, drivers -- anyone who needs to weigh material
Scale Manager	Full CRUD	Full CRUD	Full access	Operations managers, IT staff -- anyone who configures scales or corrects reading data

Scale Manager Inherits Scale User

The Scale Manager group automatically includes all Scale User permissions. You do not need to assign both groups to the same user.

Permission Details¶

Scale User can view device configurations but cannot change serial port settings, protocols, or validation ranges. They can create new readings (through the wizard or direct creation) and view all reading history, but cannot edit or delete existing readings.
Scale Manager has full control: create, edit, and delete scale devices and readings. This group should be limited to people who set up new scales or need to correct erroneous data.

Common Tasks¶

Adding a New Scale Device¶

Navigate to Scales > Configuration > Scale Devices
Click New
Enter a Name (e.g., "Floor Scale - Dock 2")
Enter the Serial Port path (e.g., /dev/ttyUSB0)
Set the Baud Rate, Data Bits, Parity, and Stop Bits to match the scale's documentation
Choose the Protocol (Continuous for most basic scales)
If using Command/Response, MT-SICS, or Custom protocol, enter the Command String
Adjust the Weight Regex if the scale's output format is unusual
Set the Unit of Measure (lb, kg, oz, or g)
Set the Minimum Valid Weight and Maximum Valid Weight for your scale
Optionally link a Warehouse
Click Save, then click Test Connection to verify

Changing a Scale's Serial Port¶

Open the device record under Scales > Configuration > Scale Devices
Update the Serial Port field with the new path
Click Save
Click Test Connection to confirm the new port works
If the test fails, the status will change to Error with a diagnostic message

Weighing Material with Tare¶

Open Scales > Operations > Weigh Item
Select the scale device
Place the empty container on the scale
Click Tare to capture the container weight
Load material into the container
Click Read to get the gross weight
Verify the Net Weight looks correct
Enter a Reference and any Notes
Click Save Reading

Finding a Specific Reading¶

Open Scales > Operations > Reading History
Type the reference, user name, or device name in the search bar
Use the date filters (Today, This Week, This Month) to narrow results
Use Group By > Device to organize by scale

Archiving an Old Scale¶

Open the device record under Scales > Configuration > Scale Devices
Open the form view for the scale
Click the gear icon and select Archive (or uncheck the Active field)
The device will no longer appear in normal lists or the wizard's device dropdown

To see archived devices, use the Archived filter in the search bar.

Technical Details¶

Models¶

Model	Type	Purpose
`sr.scale.device`	Regular (database-persisted)	Stores scale hardware configuration, serial settings, protocol, and validation rules
`sr.scale.reading`	Regular (database-persisted)	Stores each weight reading with gross/tare/net weights, timestamps, and references
`sr.scale.wizard`	Transient (temporary)	Powers the interactive weighing popup; records are automatically cleaned up by Odoo

Key Methods¶

Method	Model	What It Does
`action_test_connection()`	`sr.scale.device`	Opens the serial port, reads one value, updates device state
`action_read_weight()`	`sr.scale.device`	Reads and validates weight, updates last reading fields, returns the weight value
`_read_serial_data()`	`sr.scale.device`	Internal: opens the serial port, sends command if required, reads raw response
`_parse_weight()`	`sr.scale.device`	Internal: applies the weight regex to raw data and returns a float
`action_read()`	`sr.scale.wizard`	Reads weight from the selected device and updates the wizard form
`action_tare()`	`sr.scale.wizard`	Reads weight and sets it as the tare value
`action_save()`	`sr.scale.wizard`	Creates a permanent `sr.scale.reading` from the wizard's current values

Dependencies¶

Dependency	Type	Why
`base`	Odoo module	Core Odoo functionality
`stock`	Odoo module	Provides `stock.warehouse` for linking scales to warehouse locations
`pyserial`	Python package	Serial port communication (`import serial`). Install with `/opt/odoo17/odoo17-venv/bin/pip install pyserial`

pyserial Must Be Installed Separately

The pyserial library is not included with Odoo. If the module is installed but pyserial is missing, users will see an error when trying to read from a scale: "pyserial is not installed." Install it in the Odoo virtual environment:

/opt/odoo17/odoo17-venv/bin/pip install pyserial

Troubleshooting¶

Problem	Likely Cause	Fix
"pyserial is not installed" error	The Python package is missing from the Odoo venv	Run `/opt/odoo17/odoo17-venv/bin/pip install pyserial`
"No data received from scale"	Scale is off, cable disconnected, or wrong port path	Power on the scale, check the USB cable, verify the port with `ls /dev/ttyUSB*`
"Serial port error -- Permission denied"	The Odoo service user lacks access to the port	Add the `odoo` user to the `dialout` group: `sudo usermod -aG dialout odoo` and restart the service
"Could not extract weight from scale response"	The weight regex does not match the scale's output format	Check the Raw Data field on a reading or the server logs to see what the scale sends, then adjust the Weight Regex
Weight is outside the valid range	The min/max validation rejected the reading	Adjust Minimum Valid Weight and Maximum Valid Weight on the device, or investigate whether the scale is malfunctioning
Wizard shows no devices in dropdown	No devices have status "Connected"	Open Scale Devices, select a device, and click Test Connection to establish a connection first
Readings show wrong unit	The device's Unit of Measure does not match the physical scale	Update the Unit of Measure field on the device record