Metadata-Version: 2.4
Name: nuotec-sent2usb
Version: 0.1.1
Summary: Driver for Nuotec SENT2USB Converter
Author: Nuotec GmbH
License-Expression: MIT
License-File: LICENSE.txt
Requires-Dist: cobs>=1.2.2,<2
Requires-Dist: pyserial>=3.5,<4
Requires-Python: >=3.8
Project-URL: Repository, https://gitlab.com/nuotec/sent2usb/nuotec-sent2usb-python
Description-Content-Type: text/markdown

# Nuotec SENT2USB Python Driver

This is an alternative Python driver for the
[SENT (SAE J2716) to USB converter from uCANDevices](https://ucandevices.github.io/sentusb.html).

**IMPORTANT:** This driver requires the firmware from
[nuotec-sent2usb-firmware](https://gitlab.com/nuotec/sent2usb/nuotec-sent2usb-firmware)
to be running on the device. See the instructions below to replace the
original firmware with this firmware.

**NOTE:** For more information about the advantages and disadvantages of this
alternative firmware and Python driver compared to the original product, see
details at
[nuotec-sent2usb-firmware](https://gitlab.com/nuotec/sent2usb/nuotec-sent2usb-firmware).

## Installation

Install the package from PyPI:

```bash
pip install nuotec-sent2usb
```

## CLI Usage

The easiest way to use this driver is through its command-line interface:

```bash
$ nuotec-sent2usb --help

usage: nuotec-sent2usb [-h] [-l] [-a] [-b] [-o] [-f] [-u] [-p PORT] [-s SEND] [-i INTERVAL] [-m] [-t TICK_TIME] [-w WIDTH]

options:
  -h, --help            show this help message and exit
  -l, --list            List connected devices
  -a, --all             List all available serial ports
  -b, --bootloader      Enter DFU bootloader
  -o, --flash-option-bytes
                        Flash option bytes with dfu-util
  -f, --flash           Flash firmware with dfu-util
  -u, --update          Check & update firmware on device
  -p, --port PORT       Serial port
  -s, --send SEND       Send nibbles (e.g. '0abc')
  -i, --interval INTERVAL
                        Send data periodically in this interval [s]
  -m, --monitor         Monitor and print received SENT frames
  -t, --tick-time TICK_TIME
                        Clock tick time in microseconds
  -w, --width WIDTH     Low pulse length in ticks
```

### Flash Firmware

After you have purchased an original
[SENTToUSB device from uCANDevices](https://ucandevices.github.io/sentusb.html),
you need to replace its firmware to make it work with this Python driver.

**CAUTION:** This step may be risky. After flashing our firmware, your device won't be
compatible with the tools from uCANDevices anymore. It is recommended to back
up the original firmware on the device first, to allow restoring it at any
time.

First, instruct the original firmware to enter the bootloader (adjust
`/dev/ttyACM0` to match your serial port):

```bash
python -c "import serial,time; s=serial.Serial('/dev/ttyACM0',115200,timeout=1); s.write(b'boot\r'); time.sleep(0.3); s.close()"
```

Then flash the new firmware to it. This will require
[dfu-util](https://dfu-util.sourceforge.net/) to be available in `PATH`:

```bash
nuotec-sent2usb -f
```

### Update Firmware

If the device is already running our custom firmware, it can be updated with
a single command (the firmware binary is contained in the Python driver):

```bash
nuotec-sent2usb -u
```

### Example: List Devices

```bash
$ nuotec-sent2usb -l
/dev/ttyACM0 Nuotec SENT2USB - CDC Interface 002E002F393043022033344E
```

### Example: Send Frame (90us Tick Time, Data=123456)

```bash
$ nuotec-sent2usb -t 90 -s 123456
Firmware:   1.0.0 (9b287c72ce4c48e7c11475cbb7acde5df17e562a)
Tick Time:  90 μs
TX: status=0x1 data=[0x2, 0x3, 0x4, 0x5, 0x6] crc=0x0
```

### Example: Monitor Received Frames (90us Tick Time)

```bash
$ nuotec-sent2usb -t 90 -m
Firmware:   1.0.0 (9b287c72ce4c48e7c11475cbb7acde5df17e562a)
Tick Time:  90 μs
RX: status=0x0 data=[0x1, 0x0, 0xC, 0x3, 0xC, 0x0] crc=0xB
RX: status=0x0 data=[0x1, 0x0, 0xC, 0x3, 0xC, 0x0] crc=0xB
RX: status=0x0 data=[0x1, 0x0, 0xC, 0x3, 0xC, 0x0] crc=0xB
RX: status=0x0 data=[0x1, 0x0, 0xC, 0x3, 0xC, 0x0] crc=0xB
```

Press Ctrl+C to cancel.

## API Usage

The driver can also be used from Python directly:

```python
import time
from nuotec_sent2usb import Sent2UsbDevice, SentFrame, SentDecoder

with Sent2UsbDevice() as device:
    print(f"Firmware: {device.get_version()}")

    # Send frame
    frame = SentFrame(status=0x0, data=[0x1, 0x2, 0x3, 0x4, 0x5, 0x6])
    device.send_pulses(frame.to_pulses(5, 90))  # width [ticks] & tick time [us]
    print(f"TX: {frame}")

    # Receive frames
    decoder = SentDecoder(90)  # tick time [us]
    while True:
        for period, width in device.fetch_pulses():
            frame = decoder.process(period, width)
            if frame is not None:
                print(f"RX: {frame}")
        time.sleep(0.05)
```

For more details, see the Python files in this package.

## Disclaimer

This project is provided as-is without any guarantee for correct behavior.
It was a side project, without the goal of creating a highly reliable
production device. So far it seems to work fine, but the code is not perfect
at all and would need some deeper review, rework and more testing to get more
confidence about the quality and reliability of this product.

## Contributions

Generally, this project has been published just in case it could be useful for
other people. However, it may or may not fit your use-case. In case you are
interested in adding more functionality, bugfixing, etc., we are happy to
receive contributions (though without any guarantee that we find the time to
review & merge it - it's recommended to contact us in advance about your
intentions).

## Credits

The development of this project is kindly sponsored by
[Nuotec GmbH](https://nuotec.ch) and
[Sensirion Automotive Solutions AG](https://sensirion-automotive.com/).

Many thanks to [uCANDevices](https://ucandevices.github.io/) for developing
the hardware this firmware runs on, which is available for purchase through
their website.

## License

Released under MIT, see [LICENSE.txt](LICENSE.txt).
