{"id":29203714,"url":"https://github.com/s00d/virtualport","last_synced_at":"2026-02-14T09:06:54.385Z","repository":{"id":276081327,"uuid":"928149259","full_name":"s00d/virtualport","owner":"s00d","description":"Virtual Serial Port (PTY) Emulator","archived":false,"fork":false,"pushed_at":"2025-02-07T06:19:45.000Z","size":56,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-07T13:39:09.894Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s00d.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-06T06:26:35.000Z","updated_at":"2025-08-15T04:16:54.000Z","dependencies_parsed_at":"2025-07-02T14:40:45.583Z","dependency_job_id":null,"html_url":"https://github.com/s00d/virtualport","commit_stats":null,"previous_names":["s00d/virtualport"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/s00d/virtualport","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s00d%2Fvirtualport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s00d%2Fvirtualport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s00d%2Fvirtualport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s00d%2Fvirtualport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s00d","download_url":"https://codeload.github.com/s00d/virtualport/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s00d%2Fvirtualport/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29441156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-02T14:39:47.704Z","updated_at":"2026-02-14T09:06:54.370Z","avatar_url":"https://github.com/s00d.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Crates.io](https://img.shields.io/crates/v/virtualport?style=for-the-badge)](https://crates.io/crates/virtualport)\n[![GitHub issues](https://img.shields.io/github/issues/s00d/virtualport?style=for-the-badge)](https://github.com/s00d/virtualport/issues)\n[![GitHub stars](https://img.shields.io/github/stars/s00d/virtualport?style=for-the-badge)](https://github.com/s00d/virtualport/stargazers)\n[![Donate](https://img.shields.io/badge/Donate-Donationalerts-ff4081?style=for-the-badge)](https://www.donationalerts.com/r/s00d88)\n\n# Virtual Serial Port (PTY) Emulator\n\nA Rust-based tool to create virtual serial ports using pseudo-terminals (PTYs) with advanced features like heartbeat messages, logging, and real-time configuration.\n\n## Features\n\n- **PTY Creation**: Creates master/slave pseudo-terminal pairs.\n- **Symbolic Link**: Exposes the slave PTY via a customizable symlink (e.g., `/tmp/my_virtual_port`).\n- **Baud Rate Control**: Dynamically adjust baud rate using `/baud` commands.\n- **Parity Settings**: Configure parity bits (none/even/odd) via `/parity` commands.\n- **Heartbeat Messages**: Periodically send configurable messages to the port.\n- **Logging**: Log all communications to a file.\n- **Non-Blocking I/O**: Efficiently handle input/output without blocking threads.\n- **Echo Control**: Disable/enable terminal echo on the slave device.\n\n## Installation\n\n### Prerequisites\n- Rust and Cargo: [Install Rust](https://www.rust-lang.org/tools/install)\n- Linux/macOS (Unix-like system required)\n\n### Steps\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/s00d/virtualport.git\n   cd virtualport\n   ```\n2. Build the project:\n   ```bash\n   cargo build --release\n   ```\n\n## Usage\n\n### Basic Example\n```bash\n# Run with verbose output\nsudo cargo run -- --verbose\n\n# In another terminal, read from the virtual port\nsudo cat /tmp/my_virtual_port\n\n# Send data to the virtual port\necho \"Hello World\" \u003e /tmp/my_virtual_port\n```\n\n### Command-Line Options\n```bash\nUSAGE:\n    virtualport [OPTIONS] --link \u003cLINK\u003e\n\nOPTIONS:\n    -l, --link \u003cLINK\u003e          Symlink path for the virtual port [default: /tmp/my_virtual_port]\n    -v, --verbose              Enable verbose logging\n    --enable-echo              Keep echo enabled on the slave device\n    --init-msg \u003cINIT_MSG\u003e      Initial message to send on startup\n    --log-file \u003cLOG_FILE\u003e      Path to log file (e.g., serial.log)\n    --heartbeat \u003cHEARTBEAT\u003e    Heartbeat interval in seconds (0 = disabled)\n    --hb-msg \u003cHB_MSG\u003e          Custom heartbeat message [default: HEARTBEAT\\n]\n```\n\n### Advanced Examples\n1. **Heartbeat and Logging**:\n   ```bash\n   sudo cargo run -- \\\n     --verbose \\\n     --log-file serial.log \\\n     --heartbeat 5 \\\n     --hb-msg \"PING\\n\"\n   ```\n\n2. **Initial Message and Custom Baud Rate**:\n   ```bash\n   sudo cargo run -- \\\n     --init-msg \"INIT\" \\\n     --enable-echo\n\n   # In the program's console:\n   /baud 9600\n   ```\n\n3. **Interact Programmatically**:\n   ```bash\n   # Send commands from shell\n   echo \"/parity even\" \u003e /tmp/my_virtual_port\n   ```\n\n## Technical Details\n\n### PTY Workflow\n1. **Master/Slave Creation**: Uses `openpty` to create a PTY pair.\n2. **Symlink**: Binds the slave PTY to a user-friendly path.\n3. **Threads**:\n    - **Master Reader**: Reads data from the master PTY and prints `[Received]` messages.\n    - **Stdin Writer**: Sends user input from stdin to the master PTY.\n    - **Heartbeat**: Periodically writes heartbeat messages to the master PTY.\n4. **Configuration**:\n    - Baud rate and parity settings are applied to the slave PTY using termios.\n\n## Data Flow\n\n```mermaid\ngraph LR\n    A[User Input/Console] --\u003e|stdin| B[Stdin Writer Thread]\n    B --\u003e|writes to| C[Master PTY]\n    C --\u003e|read by| D[Master Reader Thread]\n    D --\u003e|logs/output| E[Console: Received ...]\n    F[Heartbeat Thread] --\u003e|periodic writes| C\n    C \u003c--\u003e|PTY Pair| G[Slave PTY]\n    G --\u003e|symlink| H[\"/tmp/my_virtual_port\"]\n    H --\u003e|read/write| I[External Tools e.g., `cat`, `echo`]\n    I --\u003e|writes data| H\n    G --\u003e|read by| J[Slave Reader Thread]\n    J --\u003e|writes back to| C\n```\n\n### Diagram Explanation:\n1. **User Input** (via console) is sent to the `Stdin Writer Thread`, which writes it to the **Master PTY**.\n2. **Master PTY**:\n   - Data is read by the `Master Reader Thread` and displayed as `[Received] ...`.\n   - `Heartbeat Thread` periodically writes messages (e.g., `HEARTBEAT`).\n3. **Slave PTY**:\n   - Linked to a symlink (`/tmp/my_virtual_port`).\n   - External tools (e.g., `echo`, `cat`) interact with the slave via the symlink.\n4. **Slave Reader Thread**:\n   - Reads data from the **Slave PTY** and writes it back to the **Master PTY** (loopback).\n   - Ensures data sent to the slave (e.g., via `echo`) is forwarded to the master and displayed in the console.\n\n### Key Components:\n- 🔄 **PTY Pair**: Master and slave are connected bidirectionally.\n- 📝 **Symlink**: Provides user-friendly access to the slave PTY.\n- 🧵 **Threads**: Non-blocking I/O ensures real-time communication.\n- 💓 **Heartbeat**: Optional periodic messages for monitoring.\n\n### Working with `commands.txt`\n\nThe program supports automated command-response handling through a file named `commands.txt`. This file allows you to predefine command-response pairs that the emulator will use to process incoming commands during runtime.\n\n#### How It Works:\n- **File Structure**: The file is expected to contain alternating lines: the first line of each pair is a command, and the second line is its corresponding response. For example, if the emulator receives the command matching one of these entries, it will automatically send back the associated response.\n\n- **Location**: Place `commands.txt` in the same directory from which you launch the emulator.\n\n- **Loading Commands**: Upon startup, the emulator reads `commands.txt` and loads all command-response pairs into memory. If the file is not found, the program will issue a warning and continue running without predefined commands.\n\n- **Usage in Communication**:\n   - **Incoming Data Handling**: In the reader thread, when a complete line (terminated by `\\n`) is received from the master PTY, it is checked against the loaded commands. If a match is found, the program responds with the predefined response from the file.\n   - **Interactive Input**: Similarly, if you input a command interactively via the terminal, the program checks the command against the loaded pairs and sends back the associated response if available.\n\n#### Example `commands.txt`:\n```text\nAT\nOK\nAT+CSQ\n+CSQ: 23,99\nAT+CREG?\n+CREG: 0,1\n```\n\n## Troubleshooting\n\n### Common Issues\n1. **Permission Denied**:\n    - Use `sudo` to create PTY devices and symlinks.\n    - Ensure `/tmp` has write permissions.\n\n2. **Data Not Visible in `cat`**:\n    - Enable echo with `--enable-echo` to loopback data.\n    - Ensure no other process is holding the PTY open.\n\n3. **Garbage Output**:\n    - Match baud rates between the program and external devices.\n    - Check parity settings.\n\n4. **Heartbeat Not Working**:\n    - Ensure `--heartbeat` is greater than 0.\n    - Use `--verbose` to debug.\n\n## License\nMIT License. Contributions welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs00d%2Fvirtualport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs00d%2Fvirtualport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs00d%2Fvirtualport/lists"}