License and Readme! More doc polishing

nullstalgia · nullstalgia · commit 980d6f6fcd86 · 2025-08-04T01:50:17.000-07:00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -2,72 +2,72 @@
 name: Release
 
 permissions:
-    contents: write
-    id-token: write
-    attestations: write
+  contents: write
+  id-token: write
+  attestations: write
 
 on:
-    release:
-        types: [created]
+  release:
+    types: [created]
 
 env:
-    CARGO_TERM_COLOR: always
+  CARGO_TERM_COLOR: always
 
 jobs:
-    upload-assets:
-        strategy:
-            matrix:
-                include:
-                    - target: x86_64-unknown-linux-gnu
-                      os: ubuntu-latest
-                    - target: x86_64-apple-darwin
-                      os: macos-latest
-                    - target: x86_64-pc-windows-msvc
-                      os: windows-latest
-        runs-on: ${{ matrix.os }}
-        steps:
-            - uses: actions/checkout@v4
-            - name: Get Dependencies (Linux)
-              shell: bash
-              run: sudo apt-get update && sudo apt-get install -y libudev-dev
-              if: startsWith(matrix.os, 'ubuntu')
-            # Nevermind :(
-            # After I got it working, I thought about it and realized that
-            # any subsequent releases (i.e. -pre.1) would be annoying.
-            # - name: Conditionally add -pre to built version number (Ubuntu)
-            #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'ubuntu')
-            #   run: sed -i -E 's/^(version = ")([^"]+)"/\1\2-pre"/' Cargo.toml
-            # - name: Conditionally add -pre to built version number (MacOS)
-            #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'macos')
-            #   run: sed -i '' -E 's/^(version = ")([^"]+)"/\1\2-pre"/' Cargo.toml
-            # - name: Conditionally add -pre to built version number (Windows)
-            #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'windows')
-            #   shell: pwsh
-            #   run: (Get-Content Cargo.toml) -replace '^(version = ")([^"]+)(")', '${1}${2}-pre${3}' | Set-Content Cargo.toml
-            - name: Build and Publish yap-full
-              uses: taiki-e/upload-rust-binary-action@v1
-              with:
-                  bin: yap
-                  features: yap-full
-                  target: ${{ matrix.target }}
-                  # include: LICENSE,README.md
-                  tar: unix
-                  zip: windows
-                  archive: $bin-full-$tag-$target
-                  token: ${{ secrets.GITHUB_TOKEN }}
-                  checksum: sha512
-            - name: Build and Publish yap-lite
-              uses: taiki-e/upload-rust-binary-action@v1
-              with:
-                  bin: yap
-                  features: yap-lite
-                  target: ${{ matrix.target }}
-                  # include: LICENSE,README.md
-                  tar: unix
-                  zip: windows
-                  archive: $bin-lite-$tag-$target
-                  token: ${{ secrets.GITHUB_TOKEN }}
-                  checksum: sha512
-            # - uses: actions/attest-build-provenance@v1
-            #   with:
-            #     subject-path: "**/*.tar.gz,**/*.zip"
+  upload-assets:
+    strategy:
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+          - target: x86_64-apple-darwin
+            os: macos-latest
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get Dependencies (Linux)
+        shell: bash
+        run: sudo apt-get update && sudo apt-get install -y libudev-dev
+        if: startsWith(matrix.os, 'ubuntu')
+      # Nevermind :(
+      # After I got it working, I thought about it and realized that
+      # any subsequent releases (i.e. -pre.1) would be annoying.
+      # - name: Conditionally add -pre to built version number (Ubuntu)
+      #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'ubuntu')
+      #   run: sed -i -E 's/^(version = ")([^"]+)"/\1\2-pre"/' Cargo.toml
+      # - name: Conditionally add -pre to built version number (MacOS)
+      #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'macos')
+      #   run: sed -i '' -E 's/^(version = ")([^"]+)"/\1\2-pre"/' Cargo.toml
+      # - name: Conditionally add -pre to built version number (Windows)
+      #   if: endsWith(github.event.release.tag_name, '-pre') && startsWith(matrix.os, 'windows')
+      #   shell: pwsh
+      #   run: (Get-Content Cargo.toml) -replace '^(version = ")([^"]+)(")', '${1}${2}-pre${3}' | Set-Content Cargo.toml
+      - name: Build and Publish yap-full
+        uses: taiki-e/upload-rust-binary-action@v1
+        with:
+          bin: yap
+          features: yap-full
+          target: ${{ matrix.target }}
+          include: LICENSE,README.md,example_configs
+          tar: unix
+          zip: windows
+          archive: $bin-full-$tag-$target
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checksum: sha512
+      - name: Build and Publish yap-lite
+        uses: taiki-e/upload-rust-binary-action@v1
+        with:
+          bin: yap
+          features: yap-lite
+          target: ${{ matrix.target }}
+          include: LICENSE,README.md,example_configs
+          tar: unix
+          zip: windows
+          archive: $bin-lite-$tag-$target
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checksum: sha512
+      # - uses: actions/attest-build-provenance@v1
+      #   with:
+      #     subject-path: "**/*.tar.gz,**/*.zip"
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nullstalgia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,32 @@
+# yap - A friendly serial terminal.
+
+[![Build](https://github.com/nullstalgia/yap/actions/workflows/build.yml/badge.svg)](https://github.com/nullstalgia/yap/actions/workflows/build.yml) [![Release](https://github.com/nullstalgia/yap/actions/workflows/release.yml/badge.svg)](https://github.com/nullstalgia/yap/actions/workflows/release.yml)
+
+<img width="1080" height="607" alt="a split view of yap's port selection screen and port interaction screen" src="https://github.com/user-attachments/assets/fa42e8e8-5481-4600-8c6f-532a4a86d4d9" />
+
+### Features
+
+- User-friendly interface for interacting with Serial/COM ports.
+- Optional Pseudo-shell mode to allow preparing an input before sending, with history.
+- Intelligent auto-reconnect (checks for devices with matching characteristics, if port path changes unexpectedly).
+- Text can be colored by incoming ANSI commands, or by user-created color rules, supporting matching by either regex or string literals.
+- Connect to a device from the command line by supplying USB PID+VID
+- Log recieved port data to disk as UTF-8 processed text and/or raw bytes.
+- Macros with categories to organize commonly sent payloads.
+- Support for flashing connected ESP32 devices with .bin/.elf files!
+  - Powered by [esp-rs/espflash](https://github.com/esp-rs/espflash)!
+- Support for decoding incoming bytes as [defmt](https://github.com/knurling-rs/defmt) frames.
+- Configurable keybinds, including for Macros and ESP32 flashing!
+  - Keybinds can have several actions that run in order, so you can flash a device and send setup commands if it finishes successfully.
+- Hex view to see raw contents of incoming inputs.
+- Allow hiding specific devices from Port Selection screen.
+- Releases downloaded from GitHub can self-update!
+- Cross-Platform!
+
+# Showcase
+
+### Auto-Reconnection Example:
+https://github.com/user-attachments/assets/647d0172-3f79-4d47-974d-48f344adc645
+
+### espflash Flashing Example:
+https://github.com/user-attachments/assets/d14e6aa2-51d1-489f-b8ba-ca88f74ad3d2
diff --git a/example_configs/Config.md b/example_configs/Config.md
@@ -0,0 +1,24 @@
+Most options are configurable in-app, but some settings reside solely in the `yap.toml`.
+
+```toml
+[misc]
+log_level = "Trace" ## Max Tracing log level to print
+log_tcp_socket = "127.0.0.1:7331" ## Send Tracing log events as text over TCP to this socket
+
+[espflash]
+skip_erase_confirm = false ## Skip needing to press Enter Twice when selecting Erase Flash.
+
+[updates]
+allow_pre_releases = false ## Also checking for new pre-releases when checking for updates.
+
+[ignored_devices]
+show_ttys_ports = false ## Unix only: Show the virtual console ports (/dev/ttyS*)
+usb = ["28DE:2102"] ## Ignore ports by USB VID:PID or VID:PID:Serial
+# Default set of ignored devices:
+# (You can manually remove them from the filter yourself,
+# but they will be placed back in if the field ever needs to be regenerated from defaults.)
+#
+# - Valve Index/Bigscreen Beyond's Bluetooth COM Port (Watchman)
+#    VID: 28DE, PID: 2102
+name = [] ## Ignore ports by name/path
+```
diff --git a/example_configs/macros/example_macros.toml b/example_configs/macros/example_macros.toml
@@ -4,7 +4,7 @@
 # content = "ping 1.1.1.1" ## content to send
 # line_ending = "\n\n\n" ## (optional) if not provided, uses the configured Macro line ending in Port Settings
 
-category = "Examples" ## name is optional, if missing, will use file name
+category = "Examples" ## category is optional, if missing, will use file name
 
 [[macro]]
 name = "Backspace"
diff --git a/example_configs/macros/openshock.toml b/example_configs/macros/openshock.toml
@@ -1,4 +1,4 @@
-name = "OpenShock" ## name is optional, if missing, will use file name
+category = "OpenShock" ## category is optional, if missing, will use file name
 
 [[macro]]
 name = "Version"
@@ -14,8 +14,8 @@ content = "sysinfo"
 
 [[macro]]
 name = "Get Config (JSON)"
-content = "jsonconfig "
+content = "jsonconfig"
 
 [[macro]]
 name = "Get Config (Raw)"
-content = "rawconfig "
+content = "rawconfig"
diff --git a/example_configs/macros/openshock_setup.toml b/example_configs/macros/openshock_setup.toml
@@ -1,4 +1,4 @@
-name = "OpenShock Setup" ## name is optional, if missing, will use file name
+category = "OpenShock Setup" ## category is optional, if missing, will use file name
 
 [[macro]]
 name = "Factory Reset"
diff --git a/example_configs/yap_colors.toml.blank b/example_configs/yap_colors.toml.blank
@@ -22,3 +22,48 @@
 
 # Supported colors can be seen here:
 # https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html
+
+## OpenShock Log Line Highlighting Examples
+
+# Verbose
+# [[regex]]
+# rule = '^\[\s*\d+\]\[V\]\[[^\]:]+(?::\d+)?\]'
+# color = "magenta"
+# line = true
+
+# Debug
+# [[regex]]
+# rule = '^\[\s*\d+\]\[D\]\[[^\]:]+(?::\d+)?\]'
+# color = "blue"
+# line = true
+
+# Info
+# [[regex]]
+# rule = '^\[\s*\d+\]\[I\]\[[^\]:]+(?::\d+)?\]'
+# color = "green"
+# line = true
+
+# Warning
+# [[regex]]
+# rule = '^\[\s*\d+\]\[W\]\[[^\]:]+(?::\d+)?\]'
+# color = "yellow"
+# line = true
+
+# Error
+# [[regex]]
+# rule = '^\[\s*\d+\]\[E\]\[[^\]:]+(?::\d+)?\]'
+# color = "red"
+# line = true
+
+## Misc Examples
+
+# Censor scanned networks from OpenShock captive portal
+# [[regex]]
+# rule = '[Nn]etwork\s+(.+?)\s*\(([0-9A-Fa-f:]+)\)'
+# censor = true
+
+# # \x1B[K
+# [[regex]]
+# rule = '(?-u)\x1b\x5b\x4b'
+# color = "red"
+# line = true
diff --git a/src/panic_handler.rs b/src/panic_handler.rs
@@ -1,5 +1,6 @@
 use color_eyre::Result;
 use ratatui::crossterm::event::DisableMouseCapture;
+use std::backtrace::Backtrace;
 
 pub fn initialize_panic_handler() -> Result<()> {
     let (panic_hook, eyre_hook) = color_eyre::config::HookBuilder::default()
@@ -16,6 +17,8 @@ pub fn initialize_panic_handler() -> Result<()> {
         _ = ratatui::crossterm::execute!(std::io::stdout(), DisableMouseCapture);
 
         let msg = format!("{}", panic_hook.panic_report(panic_info));
+        let backtrace = Backtrace::force_capture();
+        let backtrace_str = format!("{backtrace}");
         #[cfg(not(debug_assertions))]
         {
             eprintln!("{msg}");
@@ -34,6 +37,10 @@ pub fn initialize_panic_handler() -> Result<()> {
                 .expect("human-panic: printing error message to console failed");
         }
         tracing::log::error!("Error: {}", strip_ansi_escapes::strip_str(msg));
+        tracing::log::error!(
+            "Backtrace:\n{}",
+            strip_ansi_escapes::strip_str(backtrace_str.as_str())
+        );
 
         #[cfg(debug_assertions)]
         {
diff --git a/src/settings/mod.rs b/src/settings/mod.rs
@@ -296,6 +296,7 @@ pub struct Logging {
     #[derivative(Default(value = "true"))]
     /// Log any disconnect and reconnect events in text outputs.
     pub log_connection_events: bool,
+    // TODO maybe add option to strip ansi escapes for text output?
 }
 
 #[serde_inline_default]
@@ -650,7 +651,7 @@ pub struct Ignored {
 
 fn default_hidden_usb() -> Vec<DeserializedUsb> {
     vec![
-        // Valve Index/Bigscreen Beyond's Bluetooth COM Port
+        // Valve Index/Bigscreen Beyond's Bluetooth COM Port (Watchman)
         DeserializedUsb {
             vid: 0x28DE,
             pid: 0x2102,

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name = "OpenShock Setup" ## name is optional, if missing, will use file name`
	`1`	`+category = "OpenShock Setup" ## category is optional, if missing, will use file name`
`2`	`2`
`3`	`3`	`[[macro]]`
`4`	`4`	`name = "Factory Reset"`