### GsUsb.start()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Starts the CAN device, resetting it and applying feature flags. Must be called after set_bitrate() or set_timing().

```APIDOC
## GsUsb.start()

### Description
Resets the device, detaches it from the kernel driver on Linux/Unix if needed, applies feature flags filtered against device capability, and puts the hardware into an active CAN mode. Must be called after `set_bitrate()` or `set_timing()`.

### Method
`GsUsb.start(flags: int = None)`

### Parameters
#### Path Parameters
- **flags** (int) - Optional - Feature flags to apply, such as `GS_CAN_MODE_NORMAL`, `GS_CAN_MODE_HW_TIMESTAMP`, `GS_CAN_MODE_LISTEN_ONLY`, `GS_CAN_MODE_LOOP_BACK`.

### Response
None

### Request Example
```python
from gs_usb.gs_usb import GsUsb
from gs_usb.constants import GS_CAN_MODE_NORMAL, GS_CAN_MODE_HW_TIMESTAMP, GS_CAN_MODE_LISTEN_ONLY

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(500000)

# Default: normal mode + hardware timestamps (if device supports it)
dev.start()

# Listen-only mode (does not ACK frames, passive monitoring):
# dev.start(flags=GS_CAN_MODE_LISTEN_ONLY | GS_CAN_MODE_HW_TIMESTAMP)

# Loop-back mode (echoes TX frames back as RX, useful for testing):
# dev.start(flags=GS_CAN_MODE_LOOP_BACK)
```
```

--------------------------------

### Install gs_usb Package

Source: https://context7.com/jxltom/gs_usb/llms.txt

Install the gs_usb library using pip.

```bash
pip install gs_usb
```

--------------------------------

### Start the CAN Device

Source: https://context7.com/jxltom/gs_usb/llms.txt

Initialize the CAN device using GsUsb.start(). This resets the device, detaches it from the kernel driver if necessary, applies feature flags, and activates CAN mode. Must be called after setting bitrate or timing.

```python
from gs_usb.gs_usb import GsUsb
from gs_usb.constants import GS_CAN_MODE_NORMAL, GS_CAN_MODE_HW_TIMESTAMP, GS_CAN_MODE_LISTEN_ONLY

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(500000)

# Default: normal mode + hardware timestamps (if device supports it)
dev.start()

# Listen-only mode (does not ACK frames, passive monitoring):
# dev.start(flags=GS_CAN_MODE_LISTEN_ONLY | GS_CAN_MODE_HW_TIMESTAMP)

# Loop-back mode (echoes TX frames back as RX, useful for testing):
# dev.start(flags=GS_CAN_MODE_LOOP_BACK)
```

--------------------------------

### Full CAN Send/Receive Loop Demo

Source: https://context7.com/jxltom/gs_usb/llms.txt

An end-to-end example that sends various CAN frame types every second while continuously polling for received frames. This demonstrates a complete cycle of CAN communication.

```python
import time
from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame
from gs_usb.constants import CAN_EFF_FLAG, CAN_ERR_FLAG, CAN_RTR_FLAG

def main():
    devs = GsUsb.scan()
    if not devs:
        print("No gs_usb device found")
        return

    dev = devs[0]
    print(f"Using device: {dev}")
    print(f"Serial: {dev.serial_number}")

    if not dev.set_bitrate(250000):
        print("Failed to set bitrate")
        return

    dev.start()

    data = b"\x12\x34\x56\x78\x9A\xBC\xDE\xF0"
    frames = [
        GsUsbFrame(can_id=0x7FF, data=data),                              # SFF with data
        GsUsbFrame(can_id=0x270, data=[0x00, 0x02, 0x4F, 0x55]),          # SFF 4-byte
        GsUsbFrame(can_id=0x350, data=[0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA]),  # SFF 6-byte
        GsUsbFrame(can_id=0x7FF),                                          # SFF no data
        GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG, data=data),          # EFF with data
        GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG),                     # EFF no data
        GsUsbFrame(can_id=0x7FF | CAN_RTR_FLAG),                          # RTR
        GsUsbFrame(can_id=0x12345678 | CAN_RTR_FLAG | CAN_EFF_FLAG),      # RTR + EFF
    ]

    end_time, n = time.time() + 1, -1
    try:
        while True:
            rx = GsUsbFrame()
            if dev.read(rx, timeout_ms=1):
                print(f"RX  {rx}")

            if time.time() >= end_time:
                end_time = time.time() + 1
                n = (n + 1) % len(frames)
                if dev.send(frames[n]):
                    print(f"TX  {frames[n]}")
    except KeyboardInterrupt:
        pass
    finally:
        dev.stop()
        print("Device stopped")

if __name__ == "__main__":
    main()

# Example output:
# Using device: candleLight USB (Bus 001 Device 003: ID 1209:2323 ...)
# Serial: 0012345678ABCDEF
# TX       7FF   [8]  12 34 56 78 9A BC DE F0
# RX       7FF   [8]  12 34 56 78 9A BC DE F0
# TX       270   [4]  00 02 4F 55
# TX       350   [6]  FF EE DD CC BB AA
```

--------------------------------

### Basic CAN Message Send/Receive Demo

Source: https://github.com/jxltom/gs_usb/blob/master/README.md

This snippet demonstrates how to initialize the gs_usb device, set the bitrate, and continuously send and receive CAN messages. It includes examples of various frame types like standard, extended, error, and RTR frames. Ensure the device is connected and the correct bitrate is set before running.

```python
import time

from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame
from gs_usb.constants import (
    CAN_EFF_FLAG,
    CAN_ERR_FLAG,
    CAN_RTR_FLAG,
)


def main():
    # Find our device
    devs = GsUsb.scan()
    if len(devs) == 0:
        print("Can not find gs_usb device")
        return
    dev = devs[0]

    # Configuration
    if not dev.set_bitrate(250000):
        print("Can not set bitrate for gs_usb")
        return

    # Start device
    dev.start()

    # Prepare frames
    data = b"\x12\x34\x56\x78\x9A\xBC\xDE\xF0"
    sff_frame = GsUsbFrame(can_id=0x7FF, data=data)
    sff_none_data_frame = GsUsbFrame(can_id=0x7FF)
    err_frame = GsUsbFrame(can_id=0x7FF | CAN_ERR_FLAG, data=data)
    eff_frame = GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG, data=data)
    eff_none_data_frame = GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG)
    rtr_frame = GsUsbFrame(can_id=0x7FF | CAN_RTR_FLAG)
    rtr_with_eid_frame = GsUsbFrame(can_id=0x12345678 | CAN_RTR_FLAG | CAN_EFF_FLAG)
    rtr_with_data_frame = GsUsbFrame(can_id=0x7FF | CAN_RTR_FLAG, data=data)
    frames = [
        sff_frame,
        sff_none_data_frame,
        err_frame,
        eff_frame,
        eff_none_data_frame,
        rtr_frame,
        rtr_with_eid_frame,
        rtr_with_data_frame,
    ]

    # Read all the time and send message in each second
    end_time, n = time.time() + 1, -1
    while True:
        iframe = GsUsbFrame()
        if dev.read(iframe, 1):
            print("RX  {}".format(iframe))

        if time.time() - end_time >= 0:
            end_time = time.time() + 1
            n += 1
            n %= len(frames)

            if dev.send(frames[n]):
                print("TX  {}".format(frames[n]))


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        pass

```

--------------------------------

### GsUsb.set_bitrate()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Configures the CAN bus bitrate using pre-computed timing values. Supports standard rates and must be called before start().

```APIDOC
## GsUsb.set_bitrate()

### Description
Sets the CAN bus bitrate using pre-computed timing values for 87.5% sample point. Supports standard rates (10k, 20k, 50k, 83.3k, 100k, 125k, 250k, 500k, 800k, 1000k bps) on devices with a 48 MHz or 80 MHz clock. Must be called before `start()`. Returns `True` on success, `False` if the bitrate is unsupported for the device clock.

### Method
`GsUsb.set_bitrate(bitrate: int)`

### Parameters
#### Path Parameters
- **bitrate** (int) - Required - The desired CAN bus bitrate in bits per second (bps).

### Response
- `bool`: `True` if the bitrate was set successfully, `False` otherwise.

### Request Example
```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]

# Set to 250 kbps (common for automotive CAN)
if not dev.set_bitrate(250000):
    raise RuntimeError("Unsupported bitrate for this device")

print("Bitrate configured successfully")
```
```

--------------------------------

### Import CAN Constants and Build IDs

Source: https://context7.com/jxltom/gs_usb/llms.txt

Imports necessary CAN frame and mode flags from gs_usb.constants. Use these constants to construct valid CAN IDs and combine device operating mode flags.

```python
from gs_usb.constants import (
    CAN_EFF_FLAG,   # 0x80000000 — use 29-bit extended ID
    CAN_RTR_FLAG,   # 0x40000000 — remote transmission request
    CAN_ERR_FLAG,   # 0x20000000 — error frame

    CAN_SFF_MASK,   # 0x000007FF — 11-bit standard ID mask
    CAN_EFF_MASK,   # 0x1FFFFFFF — 29-bit extended ID mask

    GS_CAN_MODE_NORMAL,
    GS_CAN_MODE_LISTEN_ONLY,
    GS_CAN_MODE_LOOP_BACK,
    GS_CAN_MODE_ONE_SHOT,
    GS_CAN_MODE_HW_TIMESTAMP,
)

# Example: build a 29-bit CAN ID
can_id = 0x18FF50E5 | CAN_EFF_FLAG
print(hex(can_id))  # 0x9fffff... — raw wire value with EFF flag set
```

```python
from gs_usb.gs_usb import GsUsb
devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)
dev.start(flags=GS_CAN_MODE_LISTEN_ONLY | GS_CAN_MODE_HW_TIMESTAMP)
```

--------------------------------

### GsUsb.scan()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Discovers all connected gs_usb devices and returns a list of GsUsb handles. It uses pyusb's libusb1 backend and matches devices by their vendor/product IDs.

```APIDOC
## GsUsb.scan()

### Description
Returns a list of `GsUsb` handles for every connected and recognized USB CAN device. Uses `pyusb`'s `libusb1` backend and matches devices by their vendor/product IDs.

### Method
`GsUsb.scan()`

### Parameters
None

### Response
- `list[GsUsb]`: A list of `GsUsb` instances representing discovered devices.

### Request Example
```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
if not devs:
    print("No gs_usb device found")
else:
    for dev in devs:
        print(f"Found device: {dev}")
```

### Response Example
```
Found device: candleLight USB (Bus 001 Device 003: ID 1209:2323 ...)
```
```

--------------------------------

### Create CAN Frames with Flags

Source: https://context7.com/jxltom/gs_usb/llms.txt

Demonstrates how to construct CAN frames with specific flags like CAN_ERR_FLAG, CAN_RTR_FLAG, and CAN_EFF_FLAG. Use these when creating frames that need to indicate error conditions, remote transmission requests, or extended identifiers.

```python
err = GsUsbFrame(can_id=0x7FF | CAN_ERR_FLAG, data=b"\x01\x02")
print(err.is_error_frame)         # True

rtr_eff = GsUsbFrame(can_id=0x12345678 | CAN_RTR_FLAG | CAN_EFF_FLAG)
print(rtr_eff.is_remote_frame)    # True
print(rtr_eff.is_extended_id)     # True
```

--------------------------------

### Query Device Info with GsUsb

Source: https://context7.com/jxltom/gs_usb/llms.txt

Access device firmware and hardware versions via the `device_info` property. This issues a USB control request and returns a `DeviceInfo` object.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)

info = dev.device_info
print(info)
# iCount: 1
# FW Version: 2.0
# HW Version: 1.0
print(f"Channels: {info.icount}")
print(f"Firmware: {info.fw_version / 10.0}")
print(f"Hardware: {info.hw_version / 10.0}")
```

--------------------------------

### Set Low-Level CAN Bit Timing Parameters

Source: https://context7.com/jxltom/gs_usb/llms.txt

Directly configure the CAN bit timing registers on the device using GsUsb.set_timing(). This is useful for non-standard bitrates or precise control over timing segments. Must be called before GsUsb.start().

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]

# Manually set timing for 250 kbps on a 48 MHz clock device:
# prop_seg=1, phase_seg1=12, phase_seg2=2, sjw=1, brp=12
dev.set_timing(prop_seg=1, phase_seg1=12, phase_seg2=2, sjw=1, brp=12)
print("Custom timing applied")
```

--------------------------------

### GsUsb.device_info

Source: https://context7.com/jxltom/gs_usb/llms.txt

A property that queries the device for its firmware and hardware version information. Returns a DeviceInfo object.

```APIDOC
## GsUsb.device_info — Query device firmware and hardware version

A property that issues a USB control request and returns a `DeviceInfo` object containing the channel count (`icount`), firmware version, and hardware version fields.

### Method
GET (property access)

### Endpoint
`/usb/control/device_info` (conceptual)

### Response
#### Success Response (200)
- **device_info** (`DeviceInfo`) - An object containing device information.
  - **icount** (integer) - The number of channels on the device.
  - **fw_version** (integer) - The firmware version (e.g., 20 for 2.0).
  - **hw_version** (integer) - The hardware version (e.g., 10 for 1.0).

### Response Example
```json
{
  "icount": 1,
  "fw_version": 20,
  "hw_version": 10
}
```
```

--------------------------------

### Configure CAN Bus Bitrate

Source: https://context7.com/jxltom/gs_usb/llms.txt

Set the CAN bus bitrate using pre-computed timing values with GsUsb.set_bitrate(). This method supports standard bitrates and requires the device's base clock frequency (48 MHz or 80 MHz). Must be called before GsUsb.start(). Returns True on success, False if the bitrate is unsupported.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]

# Set to 250 kbps (common for automotive CAN)
if not dev.set_bitrate(250000):
    raise RuntimeError("Unsupported bitrate for this device")

# Other standard bitrates:
# dev.set_bitrate(10000)    # 10 kbps
# dev.set_bitrate(125000)   # 125 kbps
# dev.set_bitrate(500000)   # 500 kbps
# dev.set_bitrate(1000000)  # 1 Mbps

print("Bitrate configured successfully")
```

--------------------------------

### Scan for Connected gs_usb Devices

Source: https://context7.com/jxltom/gs_usb/llms.txt

Discover all connected and recognized USB CAN devices using GsUsb.scan(). This method uses pyusb's libusb1 backend and matches devices by their vendor/product IDs. It returns a list of GsUsb handles.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
if not devs:
    print("No gs_usb device found")
else:
    for dev in devs:
        print(f"Found device: {dev}")
        # e.g. "candleLight USB (Bus 001 Device 003: ID 1209:2323 ...)"

# Output:
# Found device: candleLight USB (Bus 001 Device 003: ID 1209:2323 ...)
```

--------------------------------

### GsUsb.find()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Finds a specific gs_usb device by its USB bus number and address. Returns a GsUsb instance if found, otherwise None.

```APIDOC
## GsUsb.find()

### Description
Looks up a single device by its USB bus number and address. Returns a `GsUsb` instance if found, otherwise `None`. Useful when multiple devices are connected and a specific one must be targeted.

### Method
`GsUsb.find(bus: int, address: int)`

### Parameters
#### Path Parameters
- **bus** (int) - Required - The USB bus number of the device.
- **address** (int) - Required - The USB address of the device.

### Response
- `GsUsb` or `None`: A `GsUsb` instance if the device is found, otherwise `None`.

### Request Example
```python
from gs_usb.gs_usb import GsUsb

# First scan to discover bus/address
devs = GsUsb.scan()
if devs:
    bus = devs[0].bus          # e.g. 1
    address = devs[0].address  # e.g. 3

    dev = GsUsb.find(bus=bus, address=address)
    if dev:
        print(f"Found device at bus={bus}, address={address}: {dev}")
    else:
        print("Device not found")
```
```

--------------------------------

### Query Device Capabilities with GsUsb

Source: https://context7.com/jxltom/gs_usb/llms.txt

Retrieve device timing capabilities and feature flags using the `device_capability` property. This is a cached property that returns a `DeviceCapability` object.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)

cap = dev.device_capability
print(cap)
# Feature bitfield: 0x00000014
# Clock: 48000000
# TSEG1: 1 - 16
# TSEG2: 1 - 8
# SJW (max): 4
# BRP: 1 - 1024
print(f"Supports HW timestamps: {bool(cap.feature & 0x10)}")
print(f"Base clock: {cap.fclk_can / 1e6:.0f} MHz")
```

--------------------------------

### Find a Specific gs_usb Device by Bus and Address

Source: https://context7.com/jxltom/gs_usb/llms.txt

Locate a specific USB CAN device using its bus number and address with GsUsb.find(). This is useful when multiple devices are connected and a particular one needs to be targeted. Returns a GsUsb instance if found, otherwise None.

```python
from gs_usb.gs_usb import GsUsb

# First scan to discover bus/address
devs = GsUsb.scan()
if devs:
    bus = devs[0].bus          # e.g. 1
    address = devs[0].address  # e.g. 3

    dev = GsUsb.find(bus=bus, address=address)
    if dev:
        print(f"Found device at bus={bus}, address={address}: {dev}")
    else:
        print("Device not found")
```

--------------------------------

### GsUsb.send()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Writes a packed GsUsbFrame to the device's USB bulk OUT endpoint. It automatically handles hardware timestamp inclusion based on the active CAN mode. Returns True on success.

```APIDOC
## GsUsb.send() — Transmit a CAN frame

Writes a packed `GsUsbFrame` to the device's USB bulk OUT endpoint (0x02). Automatically includes or excludes the hardware timestamp field in the wire format depending on whether `GS_CAN_MODE_HW_TIMESTAMP` was active at `start()`. Returns `True` on success.

### Method
POST (or similar, depending on underlying implementation)

### Endpoint
`/usb/bulk/out` (conceptual)

### Parameters
#### Request Body
- **frame** (`GsUsbFrame`) - Required - The CAN frame to transmit.

### Request Example
```python
from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame

dev = GsUsb.scan()[0]
dev.start()
sff = GsUsbFrame(can_id=0x123, data=b"\x01\x02\x03\x04\x05\x06\x07\x08")
dev.send(sff)
```

### Response
#### Success Response (200)
- **success** (`boolean`) - True if the frame was sent successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Construct CAN Frames with GsUsbFrame

Source: https://context7.com/jxltom/gs_usb/llms.txt

Create CAN frame objects using `GsUsbFrame`. The `can_id` field includes arbitration ID and frame-type flags. Data is zero-padded to 8 bytes internally.

```python
from gs_usb.gs_usb_frame import GsUsbFrame
from gs_usb.constants import CAN_EFF_FLAG, CAN_RTR_FLAG, CAN_ERR_FLAG

# Standard 11-bit frame (SFF), 8-byte payload
sff = GsUsbFrame(can_id=0x7FF, data=b"\x12\x34\x56\x78\x9A\xBC\xDE\xF0")
print(sff)                        # "     7FF   [8]  12 34 56 78 9A BC DE F0"
print(hex(sff.arbitration_id))    # 0x7ff
print(sff.is_extended_id)         # False

# Extended 29-bit frame (EFF)
eff = GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG, data=[0xAA, 0xBB])
print(eff)                        # "12345678   [2]  AA BB"
print(eff.is_extended_id)         # True

# Remote Transmission Request (RTR), no data
rtr = GsUsbFrame(can_id=0x7FF | CAN_RTR_FLAG)
print(rtr)                        # "     7FF   [0]  remote request"
print(rtr.is_remote_frame)        # True
```

--------------------------------

### GsUsb.read()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Reads a single CAN frame from the device's USB bulk IN endpoint into a pre-allocated GsUsbFrame. Returns True if a frame was received before the timeout, False on timeout or USB error. A timeout_ms of 0 blocks indefinitely.

```APIDOC
## GsUsb.read() — Receive a CAN frame

Reads a single CAN frame from the device's USB bulk IN endpoint (0x81) into a pre-allocated `GsUsbFrame`. Returns `True` if a frame was received before the timeout, `False` on timeout or USB error. Setting `timeout_ms=0` blocks indefinitely until a frame arrives.

### Method
GET (or similar, depending on underlying implementation)

### Endpoint
`/usb/bulk/in` (conceptual)

### Parameters
#### Query Parameters
- **timeout_ms** (integer) - Optional - The timeout in milliseconds. `0` means block indefinitely.

#### Request Body
- **frame** (`GsUsbFrame`) - Required - A pre-allocated GsUsbFrame object to store the received data.

### Request Example
```python
from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame

dev = GsUsb.scan()[0]
dev.start()
frame = GsUsbFrame()
if dev.read(frame, timeout_ms=1):
    print(f"RX  {frame}")
```

### Response
#### Success Response (200)
- **received** (`boolean`) - True if a frame was received, False otherwise.
- **frame** (`GsUsbFrame`) - The received CAN frame data if `received` is True.

#### Response Example
```json
{
  "received": true,
  "frame": {
    "arbitration_id": 123,
    "can_dlc": 8,
    "is_extended_id": false,
    "is_remote_frame": false,
    "is_error_frame": false,
    "timestamp": 12345.678901
  }
}
```
```

--------------------------------

### GsUsb.set_timing()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Directly configures the CAN bit timing registers on the device for precise control over timing segments.

```APIDOC
## GsUsb.set_timing()

### Description
Directly configures the CAN bit timing registers on the device. Useful for non-standard bitrates or precise control over timing segments. Must be called before `start()`.

### Method
`GsUsb.set_timing(prop_seg: int, phase_seg1: int, phase_seg2: int, sjw: int, brp: int)`

### Parameters
#### Path Parameters
- **prop_seg** (int) - Required - Propagation segment time.
- **phase_seg1** (int) - Required - Phase segment 1 time.
- **phase_seg2** (int) - Required - Phase segment 2 time.
- **sjw** (int) - Required - Synchronization jump width.
- **brp** (int) - Required - Baud rate prescaler.

### Response
None

### Request Example
```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]

# Manually set timing for 250 kbps on a 48 MHz clock device:
# prop_seg=1, phase_seg1=12, phase_seg2=2, sjw=1, brp=12
dev.set_timing(prop_seg=1, phase_seg1=12, phase_seg2=2, sjw=1, brp=12)
print("Custom timing applied")
```
```

--------------------------------

### Receive CAN Frames with GsUsb

Source: https://context7.com/jxltom/gs_usb/llms.txt

Receive a single CAN frame using the `read()` method. The `timeout_ms` parameter controls blocking behavior; `0` blocks indefinitely. Returns `True` if a frame is received, `False` on timeout or error.

```python
from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)
dev.start()

frame = GsUsbFrame()

# Non-blocking poll with 1 ms timeout
if dev.read(frame, timeout_ms=1):
    print(f"RX  {frame}")
    print(f"  Arbitration ID : 0x{frame.arbitration_id:X}")
    print(f"  DLC            : {frame.can_dlc}")
    print(f"  Extended ID    : {frame.is_extended_id}")
    print(f"  Remote frame   : {frame.is_remote_frame}")
    print(f"  Error frame    : {frame.is_error_frame}")
    print(f"  Timestamp (s)  : {frame.timestamp:.6f}")
    # RX       123   [8]  01 02 03 04 05 06 07 08
    #   Arbitration ID : 0x123
    #   DLC            : 8
    #   Extended ID    : False
    #   Remote frame   : False
    #   Error frame    : False
    #   Timestamp (s)  : 12345.678901
```

--------------------------------

### Send CAN Frames with GsUsb

Source: https://context7.com/jxltom/gs_usb/llms.txt

Transmit CAN frames using the `send()` method. The hardware timestamp is automatically included or excluded based on the `GS_CAN_MODE_HW_TIMESTAMP` setting. Returns `True` on success.

```python
from gs_usb.gs_usb import GsUsb
from gs_usb.gs_usb_frame import GsUsbFrame
from gs_usb.constants import CAN_EFF_FLAG, CAN_RTR_FLAG

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)
dev.start()

# Standard 11-bit frame with 8 bytes of data
sff = GsUsbFrame(can_id=0x123, data=b"\x01\x02\x03\x04\x05\x06\x07\x08")
if dev.send(sff):
    print(f"TX  {sff}")
    # TX       123   [8]  01 02 03 04 05 06 07 08

# Extended 29-bit frame
eff = GsUsbFrame(can_id=0x12345678 | CAN_EFF_FLAG, data=b"\xDE\xAD\xBE\xEF")
dev.send(eff)
# TX  12345678   [4]  DE AD BE EF

# Remote Transmission Request (no data payload)
rtr = GsUsbFrame(can_id=0x7FF | CAN_RTR_FLAG)
dev.send(rtr)
# TX       7FF   [0]  remote request
```

--------------------------------

### GsUsb.device_capability

Source: https://context7.com/jxltom/gs_usb/llms.txt

A cached property that queries the device for its timing capabilities and feature flags. Returns a DeviceCapability object.

```APIDOC
## GsUsb.device_capability — Query device timing capabilities and feature flags

A cached property that issues a USB control request and returns a `DeviceCapability` object describing the CAN controller's supported features, base clock frequency, timing segment limits, and prescaler range. The result is cached after the first call.

### Method
GET (property access)

### Endpoint
`/usb/control/device_capability` (conceptual)

### Response
#### Success Response (200)
- **device_capability** (`DeviceCapability`) - An object containing device capabilities.
  - **feature** (integer) - A bitfield representing supported features.
  - **fclk_can** (integer) - The base clock frequency for CAN timing calculations.
  - **tseg1_min** (integer) - Minimum value for TSEG1.
  - **tseg1_max** (integer) - Maximum value for TSEG1.
  - **tseg2_min** (integer) - Minimum value for TSEG2.
  - **tseg2_max** (integer) - Maximum value for TSEG2.
  - **sjw_max** (integer) - Maximum Synchronization Jump Width.
  - **brp_min** (integer) - Minimum value for the Baud Rate Prescaler.
  - **brp_max** (integer) - Maximum value for the Baud Rate Prescaler.

### Response Example
```json
{
  "feature": 20, 
  "fclk_can": 48000000,
  "tseg1_min": 1,
  "tseg1_max": 16,
  "tseg2_min": 1,
  "tseg2_max": 8,
  "sjw_max": 4,
  "brp_min": 1,
  "brp_max": 1024
}
```
```

--------------------------------

### Read Device Serial Number with GsUsb

Source: https://context7.com/jxltom/gs_usb/llms.txt

Access the device's serial number string using the `serial_number` property. This retrieves the string as reported by the firmware.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)

print(f"Serial number: {dev.serial_number}")
# Serial number: 0012345678ABCDEF
```

--------------------------------

### GsUsb.stop()

Source: https://context7.com/jxltom/gs_usb/llms.txt

Stops the CAN device by sending a reset control request, halting all CAN bus activity.

```APIDOC
## GsUsb.stop()

### Description
Sends a reset control request to the device, stopping all CAN bus activity. Silently ignores USB errors that may occur if the device has already been disconnected.

### Method
`GsUsb.stop()`

### Parameters
None

### Response
None

### Request Example
```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)
dev.start()

# ... do CAN work ...

dev.stop()
print("Device stopped")
```
```

--------------------------------

### Stop the CAN Device

Source: https://context7.com/jxltom/gs_usb/llms.txt

Cease CAN bus activity and reset the device using GsUsb.stop(). This method silently ignores USB errors that might occur if the device has already been disconnected.

```python
from gs_usb.gs_usb import GsUsb

devs = GsUsb.scan()
dev = devs[0]
dev.set_bitrate(250000)
dev.start()

# ... do CAN work ...

dev.stop()
print("Device stopped")
```

--------------------------------

### GsUsb.serial_number

Source: https://context7.com/jxltom/gs_usb/llms.txt

A property that retrieves the USB device's serial number string as reported by the firmware.

```APIDOC
## GsUsb.serial_number — Read device serial number

A property that retrieves the USB device's serial number string, as reported by the firmware.

### Method
GET (property access)

### Endpoint
`/usb/control/serial_number` (conceptual)

### Response
#### Success Response (200)
- **serial_number** (string) - The device's serial number.

### Response Example
```json
{
  "serial_number": "0012345678ABCDEF"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.