Welcome to the ws-barcode-scanner documentation!

This module is an unofficial Python interface for the Waveshare Barcode Scanner Module.


Run pip install ws-barcode-scanner to install the latest version.

Device setup

There are two ways to configure the device:

  1. By scanning the QR codes from the manual

  2. Via serial communication

To interact with the device, this library uses serial communication, which can be achieved via either the USB or the UART port. To enable serial communication via USB, the device has to be configured to use the USB port as virtual serial port.

QR codes for device configuration

QR codes for device configuration (taken from the manual)


To control the scanner, use the BarcodeScanner class.

>>> from ws_barcode_scanner import BarcodeScanner

>>> scanner = BarcodeScanner("COM3")

Barcode scanning

When the device scans a code, it sends it to the device. The method query_for_codes reads and returns all codes that were scanned since the method was last called. The properties last_code and last_timestamp store the last code that was read, and the timestamp of that event.


The method restore_factory_settings resets all user settings. save_to_flash writes the current settings to the persistent flash memory (some settings would otherwise be lost when the device is restarted).

All other configuration has to be made via the memory_map. It is an interface to the address table from the manual (pages 72-93). Note that the manual refers to the highest bit as “7”, while this library starts with “0”:

>>> # read data
>>> scanner.memory_map[0x0000, 0]  # first bit of the first byte
True  # flash LED on scan
>>> scanner.memory_map[0x0000, 1]
True  # beep on scan
>>> scanner.memory_map[0x0000, 2:4]
1  # red target LED on during scanning
>>> scanner.memory_map[0x0000, 4:6]
1  # white LED on during scanning
>>> scanner.memory_map[0x0000, 6:8]
0  # manual scanning mode

>>> # write data
>>> scanner.memory_map[0x0000, 1] = False  # no beep on scan
>>> scanner.memory_map[0x0000, 4:6] = 0b11  # keep white LED  always on

The BarcodeScanner class

class ws_barcode_scanner.BarcodeScanner(serial_port: str)[source]
memory_map: ws_barcode_scanner.memory_map.MemoryMap

Interface to the device memory

save_to_flash() None[source]

Save the current settings to the persistent flash memory

restore_factory_settings() None[source]

Restore factory settings

query_for_codes() List[bytes][source]

Query for scanned codes

property last_code: bytes

The last scanned barcode

property last_timestamp

The timestamp when the last barcode was scanned (startup time if no code was scanned yet)

Memory Map

class ws_barcode_scanner.memory_map.MemoryMap(serial_port: ws_barcode_scanner.serial_port.SerialPort)[source]

Interface to the device memory

__getitem__(item: Union[int, slice]) int[source]
__getitem__(item: Tuple[Union[int, slice], int]) bool
__getitem__(item: Tuple[Union[int, slice], slice]) int

Read data from memory


>>> # read bytes as integers
>>> self[0x0000]  # first byte
>>> bin(self[0x0000])  # same number as binary
>>> bin(self[0x0000:0x0002])  # first two bytes
>>> # read bit as bool
>>> self[0x0000, 0]  # first bit of first byte
>>> # read bit slices as integers
>>> bin(self[0x0000, 0:4])  # read first four bits of first byte
__setitem__(key: Union[int, slice], value: Union[int, bytes]) None[source]
__setitem__(key: Tuple[Union[int, slice], int], value: Union[int, bool]) None
__setitem__(key: Tuple[Union[int, slice], slice], value: Union[int, bytes]) None

Write data to memory


>>> # write bytes
>>> self[0x0000] = 0b10100101  # write `10100101` to first byte
>>> self[0x0000] = 165  # same
>>> self[0x0000] = bytes.fromhex("A5")  # same
>>> self[0x0000] = b"\xA5"  # same
>>> # write bit
>>> self[0x0000, 0] = 0  # set first bit of first byte to 0
>>> self[0x0000, 0] = False  # same
>>> # write bit slices
>>> self[0x0000, -2:] = 0b00  # set last two bits of first byte to `00`
>>> self[0x0000, -2:] = 0  # same