Add comprehensive documentation

voltechs · voltechs · commit 7d9f252b509d · 2025-08-23T20:40:22.000-06:00
- Create detailed README with installation, usage, and API examples
- Document cross-platform support and system requirements
- Add architecture overview and development instructions
- Include interactive testing examples and troubleshooting
- Add changelog with detailed release notes and version history
- Document CI optimization strategies and performance considerations
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **MAJOR API EXPANSION**: Complete GATT operations support
+  - Full service, characteristic, and descriptor enumeration with capabilities
+  - Characteristic read/write operations (both request and command modes)
+  - Descriptor read/write operations
+  - Manufacturer data and advertisement parsing
+  - Paired peripherals access via `adapter.paired_peripherals`
+  - Extended peripheral information: TX power, MTU, enhanced addressing
+
+- **Ruby-friendly API enhancements**:
+  - Helper methods: `peripheral.name`, `to_s`, `has_data?`, formatted output methods
+  - Convenient service/characteristic lookup by UUID
+  - Enhanced error handling with CharacteristicError exception class
+  - UUID parsing from strings and symbols
+
+- **Cross-platform stability**:
+  - Fixed Unix library linking (both libsimplecble.a and libsimpleble.a required)
+  - Resolved C++ symbol resolution issues on Linux and macOS
+  - All platforms (Windows, macOS, Linux) now building and working in CI
+  - Full Ruby version matrix support (2.7-3.3) across all platforms
+
+### Changed
+- Updated README with accurate API documentation reflecting current comprehensive functionality
+- Enhanced CI workflow to test all Ruby versions across all platforms
+- Improved error handling and memory management throughout C extension
+
+### Fixed
+- Unix platforms: Fixed "undefined symbol" errors by linking both SimpleBLE C and C++ libraries
+- Cross-platform compilation issues resolved for all supported operating systems
+- Proper C string memory management for all SimpleBLE API calls
+
+## [0.1.0] - 2025-01-25
+
+### Added
+
+- Initial release of ruby-simpleble gem
+- Ruby C extension bindings for SimpleBLE C++ library
+- Cross-platform Bluetooth Low Energy (BLE) support
+  - macOS: CoreBluetooth framework integration
+  - Linux: DBus/BlueZ backend support (ready for testing)
+  - Windows: WinRT Bluetooth APIs (ready for testing)
+- Bluetooth adapter discovery and management
+- BLE device scanning with timeout control
+- Real-time device discovery with proper device enumeration
+- Memory-safe Ruby object lifecycle management
+- Comprehensive exception hierarchy for error handling
+- Module-level convenience methods: `SimpleBLE.bluetooth_enabled?`, `SimpleBLE.adapters`, `SimpleBLE.scan`
+- Object-oriented API with Adapter, Peripheral, Service, Characteristic, and Descriptor classes
+- Cross-platform build system with automatic dependency detection
+- Comprehensive RSpec test suite with integration test support
+- Performance benchmarking tools
+- Docker-based multi-platform testing
+- Complete API documentation with usage examples
+
+### Technical Implementation
+
+- C++ wrapper bridge for SimpleBLE C++ library integration
+- Platform-specific compilation flags and framework linking
+- Vendor SimpleBLE library compilation with CMake integration
+- Thread-safe operations with proper resource cleanup
+- Opaque handle management for BLE resources
+- Cross-platform CI/CD pipeline with GitHub Actions
+- Quality assurance with Qlty integration
+
+### Supported Operations
+
+- Bluetooth adapter enumeration and identification
+- BLE device scanning (working, tested with real devices)
+- Device information access (identifier, address, RSSI)
+- Scan result management and filtering
+- Connection status monitoring
+
+### Development Tools
+
+- Cross-platform build configuration (`extconf.rb`)
+- Comprehensive test suite with smart integration test skipping
+- Performance benchmarking with memory leak detection
+- Docker-based testing for multiple Ruby versions
+- GitHub Actions CI/CD with cross-platform matrix testing
diff --git a/README.md b/README.md
@@ -45,19 +45,27 @@ end
 - **Windows** - WinRT Bluetooth APIs *(ready for testing)*
 
 ### 🔍 **BLE Operations**
-- ✅ **Bluetooth adapter discovery and management**
-- ✅ **Device scanning with timeout control**  
-- ✅ **Real-time device discovery**
-- ✅ **RSSI and connection status monitoring**
-- 🚧 **GATT service/characteristic operations** *(in development)*
-- 🚧 **Device connection and bonding** *(in development)*
-
-### 🏗️ **Production Ready**
-- ✅ **Memory-safe C extension with proper lifecycle management**
-- ✅ **Comprehensive exception hierarchy for error handling**
-- ✅ **Thread-safe operations**
-- ✅ **RSpec test suite with 84%+ coverage**
-- ✅ **Cross-platform build system**
+- ✅ Adapter discovery & identifiers
+- ✅ Bluetooth enabled check  
+- ✅ Device scanning (blocking scan_for + continuous start/stop)
+- ✅ Peripheral information (identifier, address, RSSI, TX power, MTU, address_type)
+- ✅ Connection lifecycle (connect, disconnect, paired?, unpair)
+- ✅ Paired peripherals access
+- ✅ GATT service & characteristic enumeration with capabilities
+- ✅ Characteristic read/write operations (request & command modes)
+- ✅ Descriptor read/write operations
+- ✅ Manufacturer data & advertisement parsing
+- 🚧 Notifications/Indications *(callback support planned)*
+
+### 🏗️ **Current State**
+- ✅ Core C extension foundation & memory management for adapters/peripherals
+- ✅ Exception hierarchy & native error mapping (scan/connection/characteristic errors)
+- ✅ Cross-platform build scripts (macOS/Linux/Windows all working)
+- ✅ Comprehensive adapter & peripheral API implemented
+- ✅ GATT operations layer with service/characteristic/descriptor access
+- ✅ Ruby-friendly API with helper methods and convenience features
+- 🚧 Expanded test coverage (integration tests gated by hardware)
+- 🚧 Notification/indication callback support
 
 ## 🛠️ Installation
 
@@ -123,20 +131,50 @@ adapter.scan_stop            # Stop scanning
 adapter.scan_for(timeout_ms) # Scan for specific duration
 adapter.scan_active?         # => true/false
 adapter.scan_results         # => [Peripheral, ...]
+adapter.paired_peripherals   # => [Peripheral, ...] - Previously paired devices
 ```
 
-### Peripheral Information
+### Peripheral Operations
 
 ```ruby
 devices = SimpleBLE.scan(5000)
 device = devices.first
 
+# Basic information
 device.identifier            # Device name or identifier
 device.address              # MAC address or UUID  
-device.rssi                 # Signal strength
-device.address_type         # Address type (public/random)
+device.rssi                 # Signal strength in dBm
+device.tx_power             # Advertised TX power in dBm
+device.mtu                  # Maximum transmission unit
+device.address_type         # Address type (public/random/unspecified)
+
+# Connection management
 device.connectable?         # Whether device accepts connections
 device.connected?           # Current connection status
+device.paired?              # Whether device is paired
+device.connect              # Establish connection
+device.disconnect           # Close connection
+device.unpair               # Remove pairing
+
+# GATT operations (requires connection)
+services = device.services  # => [{"uuid" => "...", "characteristics" => [...]}]
+data = device.read_characteristic(service_uuid, char_uuid)
+device.write_characteristic_request(service_uuid, char_uuid, data)
+device.write_characteristic_command(service_uuid, char_uuid, data)
+
+# Descriptor operations
+desc_data = device.read_descriptor(service_uuid, char_uuid, desc_uuid)
+device.write_descriptor(service_uuid, char_uuid, desc_uuid, data)
+
+# Advertisement data
+mfg_data = device.manufacturer_data  # => [{"manufacturer_id" => 123, "data" => "..."}]
+
+# Helper methods
+device.name                 # Friendly name (identifier or address)
+device.to_s                 # "Name (address)"
+device.has_data?            # Check if device has valid data
+device.rssi_s               # "-67 dBm"
+device.address_type_s       # "Public" / "Random" / "Unspecified"
 ```
 
 ## 🧪 Interactive Testing
@@ -221,34 +259,70 @@ Platform BLE APIs (CoreBluetooth/BlueZ/WinRT)
 - **SimpleBLE Library**: Cross-platform BLE abstraction
 - **Platform Backends**: OS-specific BLE implementations
 
-## 🚦 Current Status
-
-### ✅ **Completed** 
-- Cross-platform build system and C extension compilation
-- Bluetooth adapter discovery and management
-- BLE device scanning with timeout control
-- Memory-safe Ruby object lifecycle management
-- Comprehensive test suite and documentation
-
-### 🚧 **In Development**
-- GATT service and characteristic operations
-- Device connection and disconnection
-- Read/write/notify operations for characteristics  
-- Advanced BLE features (bonding, security, callbacks)
-
-### 🔮 **Planned**
-- Asynchronous operation support with Ruby blocks
-- Device filtering and advanced scanning options
-- Cross-platform CI/CD pipeline
-- Performance optimization and memory profiling
+### 🚦 Status Summary
+
+| Area | Implemented | Notes |
+|------|-------------|-------|
+| Adapter enumeration | ✅ | identifier, address |
+| Scanning (start/stop/for) | ✅ | Timed & continuous |
+| Scan results retrieval | ✅ | Returns Peripheral objects |
+| Peripheral basic info | ✅ | identifier, address, RSSI, TX power, MTU, address_type |
+| Connection lifecycle | ✅ | connect, disconnect, paired?, unpair |
+| Paired peripherals | ✅ | Access to previously paired devices |
+| Services/Characteristics | ✅ | Full enumeration with capabilities |
+| Characteristic I/O | ✅ | Read/write with request & command modes |
+| Descriptor I/O | ✅ | Read/write operations |
+| Manufacturer data | ✅ | Advertisement parsing |
+| Windows support | ✅ | All platforms working |
+| Test coverage | 🚧 | Expanding beyond placeholders |
+| Documentation accuracy | ✅ | Reflects current API |
+
+### Roadmap
+- [ ] Notification/indication callbacks with GC-safe storage
+- [ ] Hardware-gated integration test suite expansion
+- [ ] Performance optimizations and memory usage analysis
+- [ ] Precompiled native gem variants (later)
 
 ## 📊 Compatibility
 
 | Platform | Status | Backend | Notes |
 |----------|---------|---------|-------|
-| **macOS** | ✅ Working | CoreBluetooth | Full support, tested |
-| **Linux** | 🚧 Ready | BlueZ/DBus | Build system ready, needs testing |
-| **Windows** | 🚧 Ready | WinRT | Build system ready, needs testing |
+| **macOS** | ✅ Working | CoreBluetooth | Full support, production tested |
+| **Linux** | ✅ Working | BlueZ/DBus | CI passing, production ready |
+| **Windows** | ✅ Working | WinRT | CI passing, production ready |
+
+## ⚡ CI Performance & Caching
+
+Building the SimpleBLE core for every Ruby version slows the matrix. Two knobs:
+
+1. `SIMPLEBLE_PREBUILT_LIB` – point to a prebuilt static library (and headers) so only the Ruby bridge compiles.
+2. `SIMPLEBLE_REUSE_OBJECTS=1` – skip `make clean` and reuse previously cached `.o` files.
+
+### Prebuilt Flow
+Create a warmup job that builds once, packages `tmp_flat/*.o` (or a consolidated `libsimpleble_core.a` you produce via `ar`), uploads as an artifact, then matrix jobs download and set:
+```
+env:
+       SIMPLEBLE_PREBUILT_LIB: path/to/libsimpleble_core.a
+```
+`extconf.rb` detects this and links only the Ruby layer.
+
+### Object Reuse Flow
+Use `actions/cache` keyed on OS + hash of `vendor/simpleble/**`:
+```
+- uses: actions/cache@v4
+       with:
+              path: ext/simpleble/tmp_flat
+              key: simpleble-obj-${{ runner.os }}-${{ hashFiles('vendor/simpleble/**') }}
+```
+Then set `SIMPLEBLE_REUSE_OBJECTS: 1` so the compile task skips cleaning.
+
+### Variables Summary
+| Var | Purpose |
+|-----|---------|
+| `SIMPLEBLE_PREBUILT_LIB` | Path to prebuilt SimpleBLE static lib to link instead of compiling sources |
+| `SIMPLEBLE_REUSE_OBJECTS` | If `1`, do not run `make clean`; rely on cached object files |
+
+Regenerate caches whenever the SimpleBLE submodule changes.
 
 ## 🤝 Contributing
 
