### Install Pi TV Remote for Development

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Steps to set up the development environment for Pi TV Remote on macOS or Linux, including cloning the repository, creating a virtual environment, and installing development-specific dependencies.

```bash
# Clone the repository
git clone https://github.com/yourusername/pi-tv-remote.git
cd pi-tv-remote

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"
```

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

### Install Pi TV Remote on Raspberry Pi

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Instructions to install the necessary libCEC development libraries and the Pi TV Remote package on a Raspberry Pi, including setting up a Python virtual environment for isolated dependencies.

```bash
# Install libCEC development libraries
sudo apt-get update
sudo apt-get install libcec-dev python3-dev build-essential python3-venv

# Clone the repository
git clone https://github.com/yourusername/pi-tv-remote.git
cd pi-tv-remote

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the package (will automatically handle dependencies)
pip install -e .
```

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

### HDMI-CEC Media Playback Controls

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for controlling media playback, such as starting, stopping, pausing, rewinding, and fast-forwarding content. These are typically part of the User Control Pressed (0x44) message.

```APIDOC
PLAY (0x44):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Start playback - part of User Control Pressed (0x44)
```

```APIDOC
STOP (0x45):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Stop playback - part of User Control Pressed (0x44)
```

```APIDOC
PAUSE (0x46):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Pause playback - part of User Control Pressed (0x44)
```

```APIDOC
REWIND (0x48):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Rewind content - part of User Control Pressed (0x44)
```

```APIDOC
FAST_FORWARD (0x49):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Fast forward - part of User Control Pressed (0x44)
```

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

### Project Directory Structure

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Outlines the main directories and files within the `pi_tv_remote` package, showing the organization of core components like CEC adapter, utilities, and CLI.

```bash
pi_tv_remote/         # Main package directory
├── __init__.py       # Package initialization
├── cec_adapter.py    # Core CEC adapter implementation
├── cec_utils.py      # Utility functions for CEC
└── cli.py            # Command-line interface
```

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

### Development Workflow Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Provides essential `bash` commands for maintaining the `pi_tv_remote` project, including code formatting with `black` and `isort`, static type checking with `mypy`, and running tests.

```bash
# Format code
black pi_tv_remote
isort pi_tv_remote

# Run static type checking
mypy pi_tv_remote

# Run tests
./run_tests
```

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

### Python Project Dependencies

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/requirements.txt

Specifies the core Python packages required for the project, including version constraints. Notes that the 'cec' library is typically provided as a system package on Raspberry Pi.

```Python
pydantic>=2.0.0
# Note: CEC is provided by system package python3-cec on Raspberry Pi
```

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

### Basic HDMI-CEC Control with Pi TV Remote Python API

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Illustrates how to initialize the CEC adapter, register a callback function for remote button presses, and send basic commands to the TV such as power on, volume control, and standby using the Python API.

```python
from pi_tv_remote.cec_adapter import CECAdapter, CECConfig, RemoteButton

# Create configuration
config = CECConfig(device_name="MyPi")

# Initialize adapter
adapter = CECAdapter(config)
adapter.init()

# Listen for remote button presses
def on_button_press(key_code, duration):
    print(f"Button {key_code} pressed for {duration}ms")
    
    # Example: Map specific buttons to actions
    if key_code == RemoteButton.UP:
        print("Up navigation")
    elif key_code == RemoteButton.SELECT:
        print("Selected item")

adapter.add_keypress_callback(on_button_press)

# Send commands to the TV
adapter.power_on_tv()
adapter.send_remote_button(RemoteButton.VOLUME_UP)
adapter.standby_tv()
```

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

### Advanced HDMI-CEC Command Handling and TV Control in Python

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Shows how to register custom callbacks for incoming CEC commands from the TV, send various RPi-to-TV commands like setting active source, requesting power status, and sending arbitrary CEC commands using the Pi TV Remote Python API.

```python
from pi_tv_remote.cec_adapter import CECAdapter, CECConfig, RemoteButton, CECCommand

# Create and initialize the adapter
adapter = CECAdapter(CECConfig(device_name="MyDevice"))
adapter.init()

# Register for TV→RPi commands
def handle_power_status_request(opcode, from_addr, to_addr, parameters):
    print("TV is checking if we're on!")
    # Custom logic before default response

# Add a callback for when TV requests power status
adapter.add_command_callback(CECCommand.GIVE_DEVICE_POWER_STATUS, handle_power_status_request)

# Send RPi→TV commands
# Power on the TV
adapter.power_on_tv()

# Put TV in standby
adapter.standby_tv()

# Set this device as active source
adapter.set_active_source()

# Send remote button presses
adapter.send_remote_button(RemoteButton.UP)
adapter.send_remote_button(RemoteButton.SELECT)

# Request information from TV
adapter.request_power_status()
adapter.request_vendor_id()

# Send any arbitrary CEC command
adapter.send_command(CECCommand.VENDOR_COMMAND, 
                    destination=0, # TV address
                    parameters=b'\x01\x02\x03')

adapter.run()
```

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

### CEC Button Reference and Codes

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Lists supported CEC buttons with their hexadecimal codes, symbols, and descriptions. This reference is crucial for understanding the input values for remote control commands and for defining custom button callbacks.

```APIDOC
Button | Code | Symbol | Description
-------|:----:|:------:|-------------
UP | 0x01 | ⬆️ | Navigate up
DOWN | 0x02 | ⬇️ | Navigate down
LEFT | 0x03 | ⬅️ | Navigate left
RIGHT | 0x04 | ➡️ | Navigate right
SELECT | 0x00 | ⏺️ | Confirm selection
BACK | 0x0D | 🔙 | Return/exit
PLAY | 0x44 | ▶️ | Start playback
STOP | 0x45 | ⏹️ | Stop playback
PAUSE | 0x46 | ⏸️ | Pause playback
REWIND | 0x48 | ⏪ | Rewind content
FAST_FORWARD | 0x49 | ⏩ | Fast forward
BLUE | 0x71 | 🔵 | Blue function button
RED | 0x72 | 🔴 | Red function button
GREEN | 0x73 | 🟢 | Green function button
YELLOW | 0x74 | 🟡 | Yellow function button
NUMBER_0 to NUMBER_9 | 0x20-0x29 | 0️⃣-9️⃣ | Number keys
VOLUME_UP | 0x41 | 🔊 | Increase volume
VOLUME_DOWN | 0x42 | 🔉 | Decrease volume
MUTE | 0x43 | 🔇 | Mute audio
```

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

### Test CEC Connection with Pi TV Remote CLI

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Demonstrates how to use the command-line interface to test HDMI-CEC connections and observe remote control events directly. Options allow setting the OSD name of the device and specifying a run duration.

```bash
python -m pi_tv_remote.cli --name "MyPi" --duration 60
```

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

### HDMI-CEC Input and Routing Control Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands related to managing active input sources and routing changes within the HDMI-CEC network.

```APIDOC
ACTIVE_SOURCE (0x82):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Set device as active - One Touch Play & Routing Control
```

```APIDOC
SET_STREAM_PATH (0x86):
  Direction: TV→RPi (✓), RPi→TV ()
  Description: Request device to become active - Routing Control
```

```APIDOC
ROUTING_CHANGE (0x80):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Change input routing - Routing Control feature
```

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

### HDMI-CEC Device Status Query Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands used to query and report the power status of connected HDMI-CEC devices.

```APIDOC
GIVE_POWER_STATUS (0x8F):
  Direction: TV→RPi (), RPi→TV (✓)
  Description: Query TV power status - Device Power Status feature
```

```APIDOC
REPORT_POWER_STATUS (0x90):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Report power status - Device Power Status feature
```

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

### HDMI-CEC Device Information Exchange Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for exchanging device-specific information, such as OSD names, physical addresses, and vendor IDs.

```APIDOC
SET_OSD_NAME (0x47):
  Direction: TV→RPi (), RPi→TV (✓)
  Description: Set device name - Device OSD Name Transfer feature
```

```APIDOC
GIVE_OSD_NAME (0x46):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Request device name - Device OSD Name Transfer feature
```

```APIDOC
REPORT_PHYSICAL_ADDR (0x84):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Report physical address - System Information feature
```

```APIDOC
DEVICE_VENDOR_ID (0x87):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Report vendor ID - Vendor Specific Command feature
```

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

### HDMI-CEC Power Management Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for controlling the power state of connected devices, such as turning a TV on or off.

```APIDOC
STANDBY (0x36):
  Direction: TV→RPi (), RPi→TV (✓)
  Description: Turn off TV - RPi can send to put TV into standby
```

```APIDOC
IMAGE_VIEW_ON (0x04):
  Direction: TV→RPi (), RPi→TV (✓)
  Description: Turn on TV - RPi can power on TV
```

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

### HDMI-CEC Navigation Controls

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands used for navigating user interfaces, including directional movements and selection confirmation. These commands are typically encapsulated within the User Control Pressed (0x44) message.

```APIDOC
UP (0x01):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Navigate up - part of User Control Pressed (0x44)
```

```APIDOC
DOWN (0x02):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Navigate down - part of User Control Pressed (0x44)
```

```APIDOC
LEFT (0x03):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Navigate left - part of User Control Pressed (0x44)
```

```APIDOC
RIGHT (0x04):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Navigate right - part of User Control Pressed (0x44)
```

```APIDOC
SELECT (0x00):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Confirm selection - part of User Control Pressed (0x44)
```

```APIDOC
BACK/EXIT (0x0D):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Return/exit - part of User Control Pressed (0x44)
```

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

### HDMI-CEC Number Key Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for transmitting numerical inputs (0-9). Implementation consistency for these keys can vary significantly across TV manufacturers.

```APIDOC
NUMBER_0 (0x20):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 0 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_1 (0x21):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 1 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_2 (0x22):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 2 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_3 (0x23):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 3 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_4 (0x24):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 4 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_5 (0x25):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 5 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_6 (0x26):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 6 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_7 (0x27):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 7 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_8 (0x28):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 8 - part of User Control Pressed (0x44)
```

```APIDOC
NUMBER_9 (0x29):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Number key 9 - part of User Control Pressed (0x44)
```

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

### HDMI-CEC Volume Control Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for adjusting audio volume (up, down, mute). These are often intercepted and handled directly by the TV or connected audio system, leading to inconsistent RPi reception.

```APIDOC
VOLUME_UP (0x41):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Increase volume - typically handled by TV/audio system
```

```APIDOC
VOLUME_DOWN (0x42):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Decrease volume - typically handled by TV/audio system
```

```APIDOC
MUTE (0x43):
  Direction: TV→RPi (△), RPi→TV (✓)
  Description: Mute audio - typically handled by TV/audio system
```

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

### HDMI-CEC Remote Control Pass-Through Commands

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Core commands for passing remote control key presses and releases through the HDMI-CEC bus, enabling a connected device to interpret remote inputs.

```APIDOC
USER_CONTROL_PRESSED (0x44):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Key press - Remote Control Pass Through feature
```

```APIDOC
USER_CONTROL_RELEASED (0x45):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Key release - Remote Control Pass Through feature
```

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

### HDMI-CEC Color Function Buttons

Source: https://github.com/tjs-w/pi-tv-remote/blob/main/README.md

Commands for the standard color-coded function buttons (Red, Green, Yellow, Blue) found on many remote controls. These are also part of the User Control Pressed (0x44) message.

```APIDOC
RED (0x72):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Red function button - part of User Control Pressed (0x44)
```

```APIDOC
GREEN (0x73):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Green function button - part of User Control Pressed (0x44)
```

```APIDOC
YELLOW (0x74):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Yellow function button - part of User Control Pressed (0x44)
```

```APIDOC
BLUE (0x71):
  Direction: TV→RPi (✓), RPi→TV (✓)
  Description: Blue function button - part of User Control Pressed (0x44)
```

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