### Basic Usage Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

A fundamental example demonstrating how to get started with the SilhouetteDevice class. This is typically found in the README's quick-start section.

```python
from silhouette import SilhouetteDevice

# Find and connect to the first available Silhouette device
device = SilhouetteDevice()

# Perform operations with the device...
print(f"Connected to device: {device.name}")

# Close the connection when done
device.close()
```

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

### Standard Usage Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/MODULES.md

Demonstrates the typical way to instantiate SilhouetteDevice and use enumerate_devices.

```python
from py_silhouette import SilhouetteDevice, enumerate_devices

device = SilhouetteDevice()

```

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

### Device Discovery Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Provides an example of how to discover available Silhouette devices on the system. This is typically found in api-reference/enumerate_devices.md.

```python
from silhouette import enumerate_devices

# Get a list of all connected Silhouette devices
available_devices = enumerate_devices()

if available_devices:
    print("Found devices:")
    for device_info in available_devices:
        print(f"- {device_info.name} (Path: {device_info.path})")
else:
    print("No Silhouette devices found.")
```

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

### Configuration Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Demonstrates how to set and manage device configurations. This pattern is common and usually detailed in README.md under 'Common Usage Patterns'.

```python
from silhouette import SilhouetteDevice, DeviceParameters

device = SilhouetteDevice()

# Get current parameters
params = device.parameters

# Modify a parameter, e.g., set the blade depth
params.blade_depth = 4

# Apply the updated parameters
device.set_parameters(params)

device.close()
```

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

### Check Device State Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

An example demonstrating how to check the current state of the device using `get_state()` and comparing it against `DeviceState` enum values.

```python
if device.get_state() == DeviceState.ready:
    print("Ready")
```

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

### Device Enumeration and Connection

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Provides a complete example of how to discover connected Silhouette devices, retrieve their parameters, connect to a specific device, and perform basic operations like getting the device name and state.

```python
from py_silhouette import SilhouetteDevice, enumerate_devices

# List devices
for dev, params in enumerate_devices():
    print(f"Found: {params.product_name}")

# Connect and test
device = SilhouetteDevice()
print(f"Connected: {device.get_name()}")
print(f"State: {device.get_state().name}")

# Simple motion
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_home()
device.flush()
print("Complete")
```

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

### Build Documentation with Sphinx

Source: https://github.com/mossblaser/py_silhouette/blob/master/README.md

Installs documentation dependencies and builds HTML documentation locally using Sphinx. Requires 'requirements-docs.txt' to be present.

```bash
pip install -r requirements-docs.txt
cd docs/
make html
```

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

### Initialize SilhouetteDevice and Get Name

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/SilhouetteDevice.md

Demonstrates the basic workflow of connecting to a Silhouette device and retrieving its name. This is typically the first step in interacting with the cutting machine.

```python
from py_silhouette import SilhouetteDevice

# 1. Connect
device = SilhouetteDevice()
print(f"Device: {device.get_name()}")
```

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

### Motion Control Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Illustrates basic motion control commands for a Silhouette device. This is often found in the QUICK_REFERENCE.md for quick lookups.

```python
from silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Move the cutting head to a specific coordinate
device.move_to(x=10, y=20)

# Perform a cut operation (example)
device.cut(duration=1000) # duration in milliseconds

device.close()
```

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

### Integration: Load Media and Execute Plotting Sequence

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceState.md

A typical workflow example that first checks if media is loaded, prompts the user if not, verifies the device is in a ready state, executes a plotting sequence, and then waits for completion.

```python
from py_silhouette import SilhouetteDevice, DeviceState

device = SilhouetteDevice()

# Check initial state
if device.get_state() == DeviceState.unloaded:
    input("Please load media and press Enter")

# Verify device is ready
if device.get_state() != DeviceState.ready:
    raise RuntimeError("Device is not in ready state")

# Execute plotting sequence
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_home()
device.flush()

# Wait for completion
while device.get_state() == DeviceState.moving:
    time.sleep(0.1)

print(f"Finished. Device state: {device.get_state().name}")
```

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

### Enumerate and Select Silhouette Devices

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

This example shows how to discover available Silhouette devices using enumerate_devices() and allows the user to select a specific device to connect to. It prints a list of devices and prompts the user for input.

```python
from py_silhouette import SilhouetteDevice, enumerate_devices

devices = list(enumerate_devices())
for num, (usb_device, device_params) in enumerate(devices):
    print("{}: {}".format(num, device_params.name))

num = int(input("Choose a device number to use: "))
usb_device, device_params = devices[num]

d = SilhouetteDevice(usb_device, device_params)
```

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

### Typical PySilhouette Workflow

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

A comprehensive example demonstrating the standard sequence of operations: connecting to a device, configuring its settings, performing motion sequences, executing commands, and verifying the device state.

```python
from py_silhouette import SilhouetteDevice

# 1. Connect
device = SilhouetteDevice()
print(device.get_name())

# 2. Configure
device.zero_on_registration_mark(200, 100)  # Or skip to use home position
device.set_speed(500)
device.set_force(100)
device.set_tool_diameter(0.9)

# 3. Motion sequence
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_to(50, 100, use_tool=True)
device.move_home()

# 4. Execute
device.flush()

# 5. Verify
print(device.get_state())
```

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

### Example DeviceParameters for Silhouette Portrait

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Illustrates the attribute values for an original Silhouette Portrait model, including media constraints and tool ranges. Note the absence of auto-blade support.

```python
DeviceParameters(
    product_name='Silhouette Portrait',
    usb_vendor_id=0x0B4D,
    usb_product_id=0x1123,
    area_width_min=76.2,     # 3.0 inches
    area_width_max=215.9,    # 8.5 inches
    area_height_min=76.2,    # 3.0 inches
    area_height_max=1016.0,  # 40 inches
    tool_force_min=7.0,
    tool_force_max=231.0,
    tool_speed_min=100.0,
    tool_speed_max=1000.0,
    tool_diameter_min=0.0,
    tool_diameter_max=2.3,
    tool_depth_min=None,     # No auto-blade support
    tool_depth_max=None,
)
```

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

### Quick Start: Connect and Control Silhouette Device

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Connect to the first available Silhouette device, configure its tool settings (speed, force, diameter), and perform a sequence of motions including cutting.

```python
from py_silhouette import SilhouetteDevice

# Connect to first available device
device = SilhouetteDevice()

# Configure the tool
device.set_speed(500)           # 500 mm/sec
device.set_force(100)           # 100 grams
device.set_tool_diameter(0.9)   # Knife tool

# Perform a motion sequence
device.move_to(10, 10, use_tool=False)   # Move without cutting
device.move_to(50, 50, use_tool=True)    # Cut line
device.move_home()                       # Return to home
device.flush()                           # Send all commands
```

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

### Error Handling Example

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Shows how to implement robust error handling, specifically catching multiple types of errors. This is detailed in the errors.md documentation.

```python
from silhouette import SilhouetteDevice, SilhouetteError, DeviceConnectionError

try:
    device = SilhouetteDevice()
    # ... perform operations ...
    device.close()
except (SilhouetteError, DeviceConnectionError) as e:
    print(f"An error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

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

### Example DeviceParameters for Silhouette Cameo4 Pro

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Shows the attribute values for a Silhouette Cameo4 Pro, highlighting its larger media width and support for auto-blade depth settings. Note the increased maximum speed.

```python
DeviceParameters(
    product_name='Silhouette Cameo4 Pro',
    usb_vendor_id=0x0B4D,
    usb_product_id=0x1139,
    area_width_min=76.2,     # 3.0 inches
    area_width_max=609.6,    # 24 inches
    area_height_min=76.2,    # 3.0 inches
    area_height_max=1016.0,  # 40 inches
    tool_force_min=7.0,
    tool_force_max=231.0,
    tool_speed_min=100.0,
    tool_speed_max=3000.0,   # Faster than older models
    tool_diameter_min=0.0,
    tool_diameter_max=2.3,
    tool_depth_min=0,        # Auto-blade supported
    tool_depth_max=10,
)
```

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

### Get Device Name

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Retrieve the name and version of the connected Silhouette device.

```python
name = device.get_name()  # str: Device name and version
```

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

### Unit Conversion Examples

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates converting between different units such as inches to millimeters, millimeters to machine units, and grams/mm/sec to machine units. These functions are useful for translating real-world measurements into the device's internal units.

```python
mm = inch2mm(8.5)           # 8.5 inches → 215.9 mm
mu = mm2mu(100)             # 100 mm → 2000 machine units
force_mu = grams2mu(100)    # 100 grams → 15 machine units
speed_mu = mmsec2mu(500)    # 500 mm/sec → 5 machine units
```

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

### Handling NoDeviceFoundError when no Silhouette devices are connected

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/errors.md

This example demonstrates how to catch NoDeviceFoundError, which is raised when the SilhouetteDevice constructor cannot find any connected devices. It suggests printing a user-friendly message and exiting.

```python
from py_silhouette import SilhouetteDevice, NoDeviceFoundError

try:
    device = SilhouetteDevice()
except NoDeviceFoundError:
    print("Please connect a Silhouette device")
    exit(1)
```

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

### Draw a Rectangle with py_silhouette

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

This basic example demonstrates how to connect to a Silhouette device, move the plotter head to draw a 20mm x 10mm rectangle, and then return to the home position. Ensure to call flush() to send commands.

```python
from py_silhouette import SilhouetteDevice

# Connect to first available device
d = SilhouetteDevice()

# Move to (10, 10) mm as a starting point without drawing
d.move_to(10, 10, False)

# Draw the rectangle
d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

# Finish plotting and return to the home position (don't forget this!)
d.move_home()

# Flush the command buffer and wait for all commands to be acknowledged
# (nothing will happen until this is called)
d.flush()
```

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

### Access Tool Diameters

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Get the predefined tool diameters, such as 'Pen' and 'Knife', from the device parameters. These values are used for compensation.

```python
# Tool diameters
pen = device.params.tool_diameters["Pen"]
knife = device.params.tool_diameters["Knife"]
```

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

### Get Device State Names and Values

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceState.md

Demonstrates how to retrieve the human-readable name (e.g., 'ready') and the raw underlying value (e.g., b"0") of the current device state using the .name and .value attributes.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()
state = device.get_state()

# Get human-readable state name
print(f"Device state: {state.name}")  # "ready", "moving", "unloaded", etc.

# Get raw value
print(f"Raw state value: {state.value}")  # b"0", b"1", etc.
```

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

### Handling RegistrationMarkNotFoundError during zeroing

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/errors.md

This example shows how to catch RegistrationMarkNotFoundError when the device fails to locate registration marks. It provides guidance on verifying media loading, mark orientation, and surrounding whitespace.

```python
from py_silhouette import SilhouetteDevice, RegistrationMarkNotFoundError

device = SilhouetteDevice()

try:
    device.zero_on_registration_mark(200, 100)
except RegistrationMarkNotFoundError:
    print("Registration marks not found.")
    print("Verify that:")
    print("  1. Media with registration marks is loaded")
    print("  2. Marks are oriented correctly (square at top-left)")
    print("  3. Adequate white space surrounds all marks")
```

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

### Checking for AutoBlade Support before setting depth

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/errors.md

This example shows how to check if a device supports automatic blade depth adjustment by examining `device.params.tool_depth_min`. It prints a message indicating lack of support if the condition is not met.

```python
from py_silhouette import SilhouetteDevice, AutoBladeNotSupportedError

device = SilhouetteDevice()

if device.params.tool_depth_min is not None:
    device.set_depth(5)
else:
    print(f"Auto-blade not supported on {device.params.product_name}")
```

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

### Get Device Name and Version

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/SilhouetteDevice.md

Retrieve the human-readable name and version string reported by the connected Silhouette device. This is useful for identifying the specific model and firmware version.

```python
device = SilhouetteDevice()
name = device.get_name()
print(f"Connected to: {name}")
```

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

### Check Device State

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceState.md

Demonstrates how to get the current device state and compare it against DeviceState enum values to determine the operational status. Requires importing SilhouetteDevice and DeviceState.

```python
from py_silhouette import SilhouetteDevice, DeviceState

device = SilhouetteDevice()

state = device.get_state()
if state == DeviceState.ready:
    print("Device is ready to use")
elif state == DeviceState.moving:
    print("Device is currently moving")
elif state == DeviceState.unloaded:
    print("Please load media and try again")
elif state == DeviceState.paused:
    print("Device is paused; press the pause button to resume")
else:
    print(f"Unknown device state: {state}")
```

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

### Get the First Connected Device

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/enumerate_devices.md

Retrieve the first available Silhouette device from the enumeration. Includes error handling for cases where no devices are found, raising a NoDeviceFoundError.

```python
from py_silhouette import enumerate_devices, NoDeviceFoundError

try:
    device, params = next(enumerate_devices())
    print(f"Using: {params.product_name}")
except StopIteration:
    raise NoDeviceFoundError("No Silhouette devices found")
```

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

### Wait for Plotting Completion

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

This example demonstrates how to monitor the plotter's state using get_state() and wait until the plotting operation is fully completed by checking if the device is no longer in the 'moving' state. It includes a time delay for polling.

```python
import time
from py_silhouette import DeviceState

while d.get_state() == DeviceState.moving:
    time.sleep(0.5)

print("Cutting complete!")
```

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

### Catching USB/Communication Errors

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/errors.md

This example shows how to catch potential USB communication errors from PyUSB, alongside general py_silhouette DeviceErrors. It is important for diagnosing issues related to the physical connection or low-level USB communication.

```python
import usb.core
from py_silhouette import SilhouetteDevice, DeviceError

try:
    device = SilhouetteDevice()
except usb.core.USBError as e:
    print(f"USB communication error: {e}")
except DeviceError as e:
    print(f"Silhouette device error: {e}")
```

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

### Error Hierarchy

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

Overview of error types raised by the library, starting from the base DeviceError.

```text
DeviceError (base class)
  ├─ NoDeviceFoundError — No connected devices
  ├─ RegistrationMarkNotFoundError — Marks not found
  └─ AutoBladeNotSupportedError — Device too old for set_depth()
```

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

### Iterating through Supported Device Parameters

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/types.md

Demonstrates how to iterate through the predefined DeviceParameters for all supported Silhouette device models and print their product name and USB Product ID.

```python
from py_silhouette import SUPPORTED_DEVICE_PARAMETERS

for params in SUPPORTED_DEVICE_PARAMETERS:
    print(f"{params.product_name}: {params.usb_product_id:04X}")
```

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

### Get Device State

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

Retrieve the current state of the device, which can be one of the DeviceState enum values.

```python
state = device.get_state()  # Returns DeviceState enum
```

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

### Import Main Class

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/MODULES.md

Import the primary SilhouetteDevice class for device interaction.

```python
from py_silhouette import SilhouetteDevice
```

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

### SilhouetteDevice Initialization Equivalence

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/enumerate_devices.md

Demonstrates that initializing SilhouetteDevice() without arguments is equivalent to enumerating the first available device and passing it to the constructor.

```python
from py_silhouette import enumerate_devices, SilhouetteDevice

# These are equivalent:
device1 = SilhouetteDevice()

device2_usb, device2_params = next(enumerate_devices())
device2 = SilhouetteDevice(device=device2_usb, device_params=device2_params)
```

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

### Get Device State

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Retrieve the current state of the Silhouette device. Possible states include ready, moving, unloaded, paused, and unknown.

```python
state = device.get_state()  # DeviceState: Current state
# Values: DeviceState.ready, .moving, .unloaded, .paused, .unknown
```

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

### Initialize SilhouetteDevice

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/SilhouetteDevice.md

Connect to the first available Silhouette device or a specific one using provided USB device objects and parameters. If no device is found and no arguments are given, a NoDeviceFoundError is raised.

```python
from py_silhouette import SilhouetteDevice

# Connect to first available device
device = SilhouetteDevice()

# Or connect to a specific device
from py_silhouette import enumerate_devices
dev, params = next(enumerate_devices())
device = SilhouetteDevice(device=dev, device_params=params)
```

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

### Accessing Device Capabilities

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Demonstrates how to retrieve and use DeviceParameters from a SilhouetteDevice instance to check media constraints and tool ranges. It also shows how to check for auto-blade support.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()
params = device.params

# Check media constraints
print(f"Media width: {params.area_width_min} to {params.area_width_max} mm")
print(f"Media height: {params.area_height_min} to {params.area_height_max} mm")

# Check tool ranges
print(f"Speed range: {params.tool_speed_min} to {params.tool_speed_max} mm/sec")
print(f"Force range: {params.tool_force_min} to {params.tool_force_max} grams")

# Check for auto-blade support
if params.tool_depth_min is not None:
    print(f"Auto-blade depth range: {params.tool_depth_min} to {params.tool_depth_max}")
else:
    print("Auto-blade not supported on this device")
```

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

### Instantiate SilhouetteDevice

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

Create an instance of the SilhouetteDevice class to automatically connect to the first available device.

```python
from py_silhouette import SilhouetteDevice
device = SilhouetteDevice()  # Auto-connect to first device
```

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

### Check Device State

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/INDEX.md

Get the current operational state of the plotter using the get_state method. Compare the returned state with the DeviceState enumeration for conditional logic.

```python
if device.get_state() == DeviceState.ready:
    # Device is ready
```

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

### Initialize SilhouetteDevice

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Instantiate the SilhouetteDevice class to connect to a device. It can auto-connect to the first available device or connect to a specific device using provided parameters.

```python
device = SilhouetteDevice()                              # Auto-connect to first device
device = SilhouetteDevice(device=usb_dev, device_params=params)  # Connect to specific device
```

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

### Get Device Name and State

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

Retrieve the name and current state of a connected Silhouette device for diagnostic purposes. This helps in verifying the device's operational status.

```python
device_name = device.get_device_name()
device_state = device.get_device_state()
```

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

### Zero on Registration Mark and Move

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/INDEX.md

Demonstrates how to use the device to zero on a registration mark and perform movements. Ensure the device is properly initialized before use.

```python
device.zero_on_registration_mark(200, 100)
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_home()
device.flush()
```

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

### Import with Device Discovery

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/MODULES.md

Import both the SilhouetteDevice class and the enumerate_devices function for discovering connected devices.

```python
from py_silhouette import SilhouetteDevice, enumerate_devices
```

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

### Set Plotting Speed and Force

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

Adjusts the plotter's speed and force settings. This example sets the speed to the minimum and force to the maximum available, based on device parameters.

```python
d.set_speed(d.params.tool_speed_min)
d.set_force(d.params.tool_force_max)
```

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

### Poll Until Device is Ready

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceState.md

Shows how to execute motion commands and then poll the device state using a loop with a small delay until the device returns to the 'ready' state. This ensures subsequent commands are sent only after the device is idle.

```python
from py_silhouette import SilhouetteDevice, DeviceState
import time

device = SilhouetteDevice()

# Perform some motion
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_home()
device.flush()

# Wait until device is ready
while device.get_state() != DeviceState.ready:
    time.sleep(0.1)

print("Device finished and is ready for next command")
```

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

### Get Coordinate System Ranges

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Retrieves the minimum and maximum usable area dimensions for a Portrait model device in millimeters. These values define the boundaries for coordinate system operations.

```python
# Portrait model example
device.params.area_width_min    # 76.2 mm (3.0 inches)
device.params.area_width_max    # 215.9 mm (8.5 inches)
device.params.area_height_min   # 76.2 mm (3.0 inches)
device.params.area_height_max   # 1016.0 mm (40 inches)
```

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

### Enumerate and Connect to Devices

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Lists all connected Silhouette devices and allows selection based on product name. It iterates through found devices, prints their product names, and connects to the first device matching 'Cameo4'.

```python
from py_silhouette import enumerate_devices, SilhouetteDevice

# List all connected devices
for device_usb, params in enumerate_devices():
    print(f"Found: {params.product_name}")
    
    # Use a specific device
    if "Cameo4" in params.product_name:
        device = SilhouetteDevice(device=device_usb, device_params=params)
        print(f"Using: {device.get_name()}")
        break
```

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

### Access Predefined Device Parameters

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Iterates through all supported device parameter instances and prints their product name and maximum specifications. This is useful for inspecting available device configurations.

```python
from py_silhouette import SUPPORTED_DEVICE_PARAMETERS

for params in SUPPORTED_DEVICE_PARAMETERS:
    print(f"{params.product_name}: "
          f"{params.area_width_max:.1f}mm wide, "
          f"up to {params.tool_speed_max:.0f} mm/sec")
```

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

### Cut a Rectangle with Advanced Settings

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

This code block cuts a rectangle using the previously configured device, speed, and force settings. It includes moving to the start point, drawing the rectangle, and returning to home.

```python
d.move_to(10, 10, False)

d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

d.move_home()

d.flush()
```

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

### Basic Motion: Move and Draw Lines with Silhouette Device

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Demonstrates basic motion control for a Silhouette device, including moving without engaging the tool and drawing lines by engaging the tool.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Move without cutting
device.move_to(10, 20, use_tool=False)

# Draw lines
device.move_to(50, 20, use_tool=True)
device.move_to(50, 60, use_tool=True)
device.move_to(10, 60, use_tool=True)
device.move_to(10, 20, use_tool=True)
```

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

### Full Import with Types

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/MODULES.md

Imports the main class along with common types like DeviceState and DeviceParameters, and utility functions.

```python
from py_silhouette import (
    SilhouetteDevice,
    DeviceState,
    DeviceParameters,
    SUPPORTED_DEVICE_PARAMETERS,
    enumerate_devices,
)
```

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

### Import Unit Conversion Utilities

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Import various utility functions for unit conversions (inches to mm, mm to micro-inches, grams to micro-inches, mm/sec to micro-inches per second) and clamping values.

```python
from py_silhouette.device import (
    inch2mm,
    mm2mu,
    grams2mu,
    mmsec2mu,
    clamp,
)
```

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

### Connect to a Silhouette Device

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/INDEX.md

Instantiate the SilhouetteDevice class to establish a connection with a plotter. Ensure the necessary libraries are imported.

```python
from py_silhouette import SilhouetteDevice
device = SilhouetteDevice()
```

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

### SilhouetteDevice() Constructor

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Initializes a SilhouetteDevice object. It can auto-connect to the first available device or connect to a specific device using provided USB details and parameters.

```APIDOC
## SilhouetteDevice()

### Description
Initializes a SilhouetteDevice object. It can auto-connect to the first available device or connect to a specific device using provided USB details and parameters.

### Parameters
- `device` (object, optional): Specific USB device object to connect to.
- `device_params` (object, optional): Parameters for the specific device.

### Usage
```python
device = SilhouetteDevice()                              # Auto-connect to first device
device = SilhouetteDevice(device=usb_dev, device_params=params)  # Connect to specific device
```

### Attributes
- `device.params` (DeviceParameters): DeviceParameters for this device.
```

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

### Supported Devices List

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

List of Silhouette device models compatible with the py_silhouette library.

```text
Silhouette Portrait, Portrait2, Portrait3, Portrait4
Silhouette Cameo, Cameo2, Cameo3, Cameo4, Cameo4 Plus, Cameo4 Pro
```

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

### Conditional Logic Based on Device State

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceState.md

Illustrates using conditional logic to execute specific actions based on the device's current state. It handles 'ready' and 'moving' states for operations, and raises an error if the media is 'unloaded'.

```python
from py_silhouette import SilhouetteDevice, DeviceState

device = SilhouetteDevice()

state = device.get_state()
if state in (DeviceState.ready, DeviceState.moving):
    # Media is loaded and device is operational
    device.set_speed(500)
    device.move_to(10, 10, use_tool=False)
    device.move_to(50, 50, use_tool=True)
    device.move_home()
    device.flush()
elif state == DeviceState.unloaded:
    print("Load media before plotting")
    raise RuntimeError("Device not ready")
```

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

### Instantiate SilhouetteDevice from Enumeration

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/enumerate_devices.md

Create a SilhouetteDevice object using a device obtained from enumerate_devices(). This shows how to pass the enumerated USB device and its parameters to the SilhouetteDevice constructor.

```python
from py_silhouette import enumerate_devices, SilhouetteDevice

# Use second device
devices = list(enumerate_devices())
if len(devices) > 1:
    device_usb, device_params = devices[1]
    device = SilhouetteDevice(device=device_usb, device_params=device_params)
    print(device.get_name())
```

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

### enumerate_devices(supported_device_parameters)

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Discovers and returns a list of available Silhouette devices along with their supported parameters. This function can optionally filter devices based on supported parameters.

```APIDOC
## enumerate_devices(supported_device_parameters=SUPPORTED_DEVICE_PARAMETERS)

### Description
Discovers and returns a list of available Silhouette devices along with their supported parameters. This function can optionally filter devices based on supported parameters.

### Parameters
- `supported_device_parameters` (list, optional): A list of device parameters to filter by. Defaults to `SUPPORTED_DEVICE_PARAMETERS`.

### Returns
- A list of tuples, where each tuple contains a device object and its parameters.

### Usage
```python
for device_usb, params in enumerate_devices():
    print(params.product_name)
```
```

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

### Error Handling for No Devices Found

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/enumerate_devices.md

Illustrates robust error handling by checking if any devices were enumerated before attempting to use them. Raises a NoDeviceFoundError if the list of devices is empty.

```python
from py_silhouette import enumerate_devices, NoDeviceFoundError

devices = list(enumerate_devices())
if not devices:
    raise NoDeviceFoundError("No Silhouette devices found")

device, params = devices[0]
print(f"Using device: {params.product_name}")
```

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

### Device Enumeration

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for discovering and enumerating available Silhouette devices connected to the system.

```APIDOC
## enumerate_devices

### Description
This function scans the system for connected Silhouette devices and returns a list of available devices.

### Usage
```python
from py_silhouette import enumerate_devices

connected_devices = enumerate_devices()
for device_info in connected_devices:
    print(f"Found device: {device_info.name} at {device_info.path}")
```

### Parameters
None

### Returns
- A list of `Device` objects, each containing information about a discovered device.
```

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

### SilhouetteDevice Class Methods

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Reference for the main device control class, SilhouetteDevice, including its constructor and various methods for controlling plotter operations.

```APIDOC
## SilhouetteDevice Class

### Description

The main class for controlling Silhouette plotters. It provides methods for initialization, motion control, tool configuration, device status, and buffer management.

### Methods

1.  **`__init__(device, device_params)`**
    *   **Description**: Constructor for the SilhouetteDevice class.
    *   **Parameters**:
        *   `device`: The device object to control.
        *   `device_params`: Device capability descriptor.

2.  **`get_name()`**
    *   **Description**: Retrieves the device name and version.
    *   **Returns**: String representing the device name and version.

3.  **`get_state()`**
    *   **Description**: Gets the current state of the device.
    *   **Returns**: An instance of `DeviceState` enum representing the current state.

4.  **`move_to(x, y, use_tool)`**
    *   **Description**: Controls the motion of the cutting tool to a specified position.
    *   **Parameters**:
        *   `x` (float): The target X-coordinate.
        *   `y` (float): The target Y-coordinate.
        *   `use_tool` (bool): Whether to engage the tool at the target position.

5.  **`move_home()`**
    *   **Description**: Moves the cutting tool back to the home position.

6.  **`set_speed(speed)`**
    *   **Description**: Configures the cutting speed.
    *   **Parameters**:
        *   `speed` (int): The desired speed value.

7.  **`set_force(force)`**
    *   **Description**: Configures the cutting force.
    *   **Parameters**:
        *   `force` (int): The desired force value.

8.  **`set_tool_diameter(diameter)`**
    *   **Description**: Sets the diameter of the cutting tool.
    *   **Parameters**:
        *   `diameter` (float): The tool diameter.

9.  **`set_depth(depth)`**
    *   **Description**: Sets the auto-blade depth.
    *   **Parameters**:
        *   `depth` (int): The auto-blade depth value.

10. **`zero_on_registration_mark(...)`**
    *   **Description**: Performs calibration using a registration mark.
    *   **Parameters**: (Details depend on specific implementation, refer to `SilhouetteDevice.md`)

11. **`flush()`**
    *   **Description**: Manages the buffer, ensuring all commands are sent to the device.

12. **`_send(data)`**
    *   **Description**: Internal method for sending data to the device. Documented for reference.
    *   **Parameters**:
        *   `data` (bytes): The data to send.

13. **`_receive(size, timeout)`**
    *   **Description**: Internal method for receiving data from the device. Documented for reference.
    *   **Parameters**:
        *   `size` (int): The number of bytes to receive.
        *   `timeout` (float): The receive timeout in seconds.

```

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

### Connect to a Specific Silhouette Device

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

Construct a SilhouetteDevice object by providing the chosen USB device and its corresponding DeviceParameters. Ensure you have selected the correct device before instantiation.

```python
from py_silhouette.device import SilhouetteDevice
from py_silhouette.device_parameters import DeviceParameters

# Assuming 'usb_device' and 'device_params' are obtained elsewhere
# device = SilhouetteDevice(usb_device, device_params)
```

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

### Basic Device Control and Motion

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

Connect to a Silhouette device, configure tool settings like speed, force, and diameter, and execute basic motion commands including moving to coordinates and returning to home. Ensure commands are sent to the device using flush().

```python
from py_silhouette import SilhouetteDevice

# Connect to device
device = SilhouetteDevice()

# Configure tool
device.set_speed(500)       # mm/sec
device.set_force(100)       # grams
device.set_tool_diameter(0.9)  # mm

# Execute motion
device.move_to(10, 10, use_tool=False)   # Move without cutting
device.move_to(50, 50, use_tool=True)    # Cut line to (50,50)
device.move_home()                       # Return to home
device.flush()                           # Send commands to device
```

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

### Configure Tool Parameters Within Device Limits

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Sets the tool speed, force, and depth to a percentage of their maximum values. Auto-blade depth is set if supported by the device.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Set speed to 75% of maximum
speed = device.params.tool_speed_min + \
        (device.params.tool_speed_max - device.params.tool_speed_min) * 0.75
device.set_speed(speed)

# Set force to 50% of maximum
force = device.params.tool_force_min + \
        (device.params.tool_force_max - device.params.tool_force_min) * 0.5
device.set_force(force)

# Set auto-blade depth if supported
if device.params.tool_depth_min is not None:
    mid_depth = int((device.params.tool_depth_min + device.params.tool_depth_max) / 2)
    device.set_depth(mid_depth)
```

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

### Enumerate Silhouette Devices

Source: https://github.com/mossblaser/py_silhouette/blob/master/docs/source/index.md

Discover connected Silhouette devices to prepare for connection. This is the first step in constructing a SilhouetteDevice object.

```python
from py_silhouette.device import SilhouetteDevice

devices = SilhouetteDevice.enumerate_devices()
```

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

### Discover Connected Silhouette Devices

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/INDEX.md

Use the enumerate_devices function to find all connected Silhouette devices. It yields device objects and their parameters, allowing you to identify them by product name.

```python
from py_silhouette import enumerate_devices

for device_usb, params in enumerate_devices():
    print(params.product_name)
```

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

### Use Standard Tool Diameters

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Illustrates how to set the tool diameter for a specific tool, like a pen, using the device parameters obtained from the SilhouetteDevice instance.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Set pen tool (fixed, no swivel compensation)
pen_diameter = device.params.tool_diameters.get("Pen", 0.0)
device.set_tool_diameter(pen_diameter)
```

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

### Checking Auto-Blade Depth Support

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/types.md

Demonstrates how to check if auto-blade depth is supported before setting it.

```python
device.params.tool_depth_min   # None if auto-blade unsupported
device.params.tool_depth_max   # None if auto-blade unsupported
```

```python
if device.params.tool_depth_min is not None:
    device.set_depth(5)
```

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

### Configure Device Speed, Force, and Tool Diameter

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/INDEX.md

Sets the operational parameters for the cutting device, including speed, force, and tool diameter. Units are specified in comments.

```python
device.set_speed(500)          # mm/sec
device.set_force(100)          # grams
device.set_tool_diameter(0.9)  # mm
```

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

### Discover Connected Devices

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/START_HERE.md

Find all Silhouette devices connected to the system.

```python
enumerate_devices()
```

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

### Command Buffering and Flushing

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Demonstrates queuing multiple movement commands and then sending them to the device in a batch using flush(). Always call flush() at the end of a motion sequence.

```python
device.move_to(10, 10, use_tool=False)  # Queued
device.move_to(50, 50, use_tool=True)   # Queued
device.move_home()                       # Queued

# All commands are sent here:
device.flush()
```

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

### Access Device Media Constraints

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Read the minimum and maximum dimensions (width and height) of the media that the device can handle, as defined in the device parameters.

```python
# Media constraints
width_min = device.params.area_width_min
width_max = device.params.area_width_max
height_min = device.params.area_height_min
height_max = device.params.area_height_max
```

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

### Basic Device Movement

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Illustrates how to move the device's tool to specific coordinates within the defined coordinate system. The `use_tool` parameter controls whether the cutting tool is engaged during the move.

```python
device.move_to(0, 0, use_tool=False)      # Top-left
device.move_to(100, 100, use_tool=False)  # 100mm right, 100mm down
```

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

### Monitor Device State and Execute Operations

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Checks the device's current state before executing motion commands and then monitors its state to wait for completion. This ensures operations are performed only when the device is ready and confirms when they are finished.

```python
from py_silhouette import SilhouetteDevice, DeviceState
import time

device = SilhouetteDevice()

# Check state before operations
state = device.get_state()
if state != DeviceState.ready:
    print(f"Device not ready: {state.name}")

# Execute motion
device.move_to(10, 10, use_tool=False)
device.move_to(50, 50, use_tool=True)
device.move_home()
device.flush()

# Wait for completion
while device.get_state() == DeviceState.moving:
    time.sleep(0.1)
```

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

### Configure Material Cutting Settings

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/README.md

Sets the speed and force parameters for different material types. Light materials require higher speed and lower force, while heavy materials need lower speed and higher force. Supports auto-blade depth if the device has this feature.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Light cutting (thin paper)
device.set_speed(device.params.tool_speed_max)
device.set_force(device.params.tool_force_min)

# Heavy cutting (thick material)
device.set_speed(device.params.tool_speed_min)
device.set_force(device.params.tool_force_max)

# With auto-blade depth (if supported)
if device.params.tool_depth_min is not None:
    device.set_depth(5)
```

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

### Troubleshooting RegistrationMarkNotFoundError with automatic and manual search

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/errors.md

This snippet demonstrates a troubleshooting approach for RegistrationMarkNotFoundError. It first attempts an automatic search and, if that fails, prompts the user to manually position the device before attempting a manual zeroing.

```python
from py_silhouette import SilhouetteDevice, RegistrationMarkNotFoundError

device = SilhouetteDevice()

# Try with automatic search from home
try:
    device.zero_on_registration_mark(200, 100, search=True)
except RegistrationMarkNotFoundError:
    print("Automatic search failed")
    
    # Try manual positioning (if possible)
    try:
        input("Manually position device over top-left mark, then press Enter")
        device.zero_on_registration_mark(200, 100, search=False)
    except RegistrationMarkNotFoundError:
        print("Manual positioning also failed")
```

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

### Setting Tool Diameter for Pen

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/DeviceParameters.md

Shows how to retrieve the standard diameter for the 'Pen' tool from DeviceParameters and set it on a SilhouetteDevice instance. This is used for tools with a fixed diameter.

```python
from py_silhouette import SilhouetteDevice

device = SilhouetteDevice()

# Set pen tool (fixed, no swivel compensation)
pen_diameter = device.params.tool_diameters.get("Pen", 0.0)
device.set_tool_diameter(pen_diameter)

```

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

### Utilities

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for utility functions, including unit conversions and other helper operations.

```APIDOC
## utilities

### Description
This module contains various utility functions that assist in common tasks, such as converting between different measurement units (e.g., mm to inches).

### Usage
```python
from py_silhouette import utilities

mm_value = 100
inch_value = utilities.mm_to_inches(mm_value)
print(f"{mm_value}mm is {inch_value} inches")
```

### Functions
- `mm_to_inches(mm: float) -> float`: Converts millimeters to inches.
- `inches_to_mm(inches: float) -> float`: Converts inches to millimeters.

(Additional utility functions may be documented in `api-reference/utilities.md`)
```

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

### Handle Registration Mark Not Found Exception

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/QUICK_REFERENCE.md

Shows how to handle the `RegistrationMarkNotFoundError` exception, which is raised if the device cannot locate the specified registration marks during calibration.

```python
try:
    device.zero_on_registration_mark(200, 100)
except RegistrationMarkNotFoundError:
    print("Marks not found")
```

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

### SilhouetteDevice Constructor

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/api-reference/SilhouetteDevice.md

Initializes and connects to a Silhouette plotter or cutter device. It can automatically detect the device or accept a specific USB device object and custom parameters.

```APIDOC
## SilhouetteDevice Constructor

### Description
Initialize and connect to a Silhouette plotter or cutter device.

### Signature
```python
def __init__(self, device=None, device_params=None)
```

### Parameters
#### Path Parameters
- **device** (`pyusb.core.Device`) - Optional - The USB device object for the plotter to control. If not provided, the first enumerated device is used.
- **device_params** (`DeviceParameters`) - Optional - Device parameters defining hardware characteristics. If not provided, parameters are looked up by USB vendor/product ID.

### Returns
None (initializes the instance)

### Raises
- `NoDeviceFoundError`: When no arguments are provided and no connected devices are found.

### Example
```python
from py_silhouette import SilhouetteDevice

# Connect to first available device
device = SilhouetteDevice()

# Or connect to a specific device
from py_silhouette import enumerate_devices
dev, params = next(enumerate_devices())
device = SilhouetteDevice(device=dev, device_params=params)
```

### Instance Attribute
- `params`: The `DeviceParameters` object passed during construction or selected automatically. Contains information about device capabilities, media limits, and tool specifications.
```

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

### DeviceState Enum Values and Comparison

Source: https://github.com/mossblaser/py_silhouette/blob/master/_autodocs/types.md

Illustrates how to access the name and value of DeviceState enum members and how to compare a device's current state with enum members.

```python
class DeviceState(enum.Enum):
    ready: b"0"
    moving: b"1"
    unloaded: b"2"
    paused: b"3"
    unknown: None

# Example usage:
# state = device.get_state()
# if state == DeviceState.ready:  # Direct comparison
# if state.name == "ready":        # By name string
# if state.value == b"0":          # By value
```