Skip to content
Tres Finocchiaro edited this page Aug 13, 2023 · 12 revisions

Compatibility

  • ✅ 2.2 | ✅ 2.1 | ⛔ 2.0 | ⛔ 1.9 | ...

Summary

Read and write data to a serial, parallel or virtual serial port.

List Serial Ports

qz.serial.findPorts().then(function(ports) {
   console.log(ports);
}).catch(displayError);

Open and Close Ports

  • Open a serial port: openPort(port, bounds)

    var properties = {
       rx: {
          start: '\x02',
          end: '\x0D',
          width: null
       },
    
       baudRate: 9600,
       dataBits: 8,
       stopBits: 1,
       parity: 'NONE',
       flowControl: 'NONE'
    };
    
    // WARNING:  Since 2.0.7 baud properties should be set here in openPort()
    qz.serial.openPort('COM1', properties).then(function() { // or '/dev/ttyUSB0', etc
        console.log('COM1 opened');
    }).catch(function(err) {
        console.error(err);
    });
    • Note: For versions 2.0 and older, the properties syntax does not use the rx { } object, but instead uses start, end, width. Backwards support for the 2.0 syntax is deprecated in 2.1 versions.
  • Close a serial port closePort(port)

    qz.serial.closePort('COM1').then(function() {  // or '/dev/ttyUSB0', etc
        console.log('COM1 closed');
    }).catch(function(err) {
        console.error(err);
    });

Send String Data

  • Send data to the open serial port via sendData(port, data, properties)

    Note: The default sendData() settings must be changed for Mettler Toledo scales

    var data = 'hi, serial port\n'; // or since 2.1.1: { type: 'plain', data: '...' }
    
    // WARNING:  sendData() properties are deprecated in 2.0.7.  Baud properties should be set in openPort() instead.
    qz.serial.sendData('COM1', data).catch(displayError);

Send Hex Data

Since 2.1.1

  • Send data to the open serial port via sendData(port, data, properties)

    var data = {
       type: 'hex',
       data: 'x68x65x6Cx6Cx6Fx0A' // 'hello\n'
    };
    
    qz.serial.sendData('COM1', data).catch(displayError);

Send File Data

Since 2.1.1

  • Send data to the open serial port via sendData(port, data, properties)

    var data = {
       type: 'file',
       data: 'mydirectory/myfile.txt'
    };
    
    qz.serial.sendData('COM1', data).catch(displayError);

Send Base64 Data

Since 2.1.1

  • Send data to the open serial port via sendData(port, data, properties)

    var data = {
       type: 'base64',
       data: 'aGVsbG8K' // 'hello\n'
    };
    
    qz.serial.sendData('COM1', data).catch(displayError);

Mettler Toledo

The default settings need to be changed for serial communication to work with Mettler Toledo scales. For other scale types, see issue #1158.

var data = 'W\n';   // <--- Weight command - Also works with 'W\r'

var properties = {
   // ...

   baudRate: 9600,
   dataBits: 7,     // <--- Changed from 8
   stopBits: 1,
   parity: 'EVEN',  // <--- Changed from NONE
   flowControl: 'NONE'
};

// WARNING:  sendData() properties are deprecated in 2.0.7.  Baud properties should be set in openPort() instead.
qz.serial.sendData('COM1', data, properties).catch(displayError);

Process Results

  1. Use a callback for processing the data returned from the serial port.

    qz.serial.setSerialCallbacks(function(evt) {
       if (evt.type !== 'ERROR') {
          console.log('Serial', evt.portName, 'received output', evt.output);
       } else {
          console.error(evt.exception);
       }
    });

Troubleshooting

Linux Permission Denied

If no ports will list or if you receive Permission denied in Linux (bugs.launchpad.net#949597)

Error: Port name - /dev/ttyUSB0; Method name - openPort(); Exception type - Permission denied.
  1. Run the following command:

    sudo usermod -a -G dialout "$USER"
  2. Log out of the desktop (or reboot)

  3. Log in to the desktop, try again