https://github.com/metaneutrons/knxmonitor
Enterprise-grade KNX/EIB bus monitoring and debugging tool built with modern .NET 9
https://github.com/metaneutrons/knxmonitor
building-automation csharp debugging dotnet eib enterprise iot knx monitoring smart-home
Last synced: 10 months ago
JSON representation
Enterprise-grade KNX/EIB bus monitoring and debugging tool built with modern .NET 9
- Host: GitHub
- URL: https://github.com/metaneutrons/knxmonitor
- Owner: metaneutrons
- License: gpl-3.0
- Created: 2025-08-10T12:29:08.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-10T13:43:44.000Z (10 months ago)
- Last Synced: 2025-08-10T14:36:19.594Z (10 months ago)
- Topics: building-automation, csharp, debugging, dotnet, eib, enterprise, iot, knx, monitoring, smart-home
- Language: C#
- Size: 122 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# KNX Monitor
[](https://github.com/metaneutrons/KnxMonitor/actions)
[](https://github.com/metaneutrons/KnxMonitor/actions)
[](https://github.com/metaneutrons/KnxMonitor/pkgs/container/knxmonitor)
[](https://www.gnu.org/licenses/GPL-3.0)
[](https://dotnet.microsoft.com/download/dotnet/9.0)
> **KNX/EIB bus monitoring and debugging tool built with modern .NET 9**
KNX Monitor is a command-line application for monitoring, debugging, and analyzing KNX/EIB building automation networks. Built with best-practice architecture patterns, it provides real-time visualization of KNX bus traffic with comprehensive logging and analysis capabilities.
## ✨ Features
- **Real-time KNX bus monitoring** with millisecond precision
- **Multiple connection types**: IP Tunneling, IP Routing, USB
- **Group address resolution** via CSV database import
- **Data Point Type (DPT) decoding** for human-readable values
- **Advanced filtering** with regex pattern support
- **Health check endpoints** for monitoring integration
- **Docker containerization** with multi-architecture support
- **Cross-platform compatibility** (Windows, macOS, Linux)
## 🚀 Quick Start
### Installation
#### Homebrew (macOS/Linux)
```bash
brew install metaneutrons/tap/knxmonitor
```
#### Docker
```bash
docker run --rm -it ghcr.io/metaneutrons/knxmonitor:latest --help
```
#### Local Docker Build
```bash
# Git-based build (default Dockerfile)
docker build -t knxmonitor:local .
# CI/CD build (requires pre-built binaries)
docker build -f Dockerfile.ci -t knxmonitor:ci .
```
#### Manual Installation
Download the latest release from [GitHub Releases](https://github.com/metaneutrons/KnxMonitor/releases).
### Basic Usage
```bash
# Show version information
knxmonitor --version
# Show help and all options
knxmonitor --help
# Monitor KNX bus via IP tunneling
knxmonitor --connection-type tunneling --host 192.168.1.100
# Monitor with group address database
knxmonitor --connection-type routing --csv-path knx_addresses.csv
# Monitor with filtering
knxmonitor --connection-type tunneling --host 192.168.1.100 --filter "1/1/*"
# Run with health check endpoint
knxmonitor --connection-type routing --health-check-port 8080
```
## 📋 Version Information
Get concise version and GitVersion information:
```bash
knxmonitor --version
```
**Example output:**
```
Version: 1.0.1
GitVersion: 1.0.1+Branch.main.Sha.8c6f5fd4d70c35e1d68e8fd5d0a7cb1e50bfbe21
```
- **Version**: Semantic version from GitVersion
- **GitVersion**: Full GitVersion string with build metadata and commit SHA
Perfect for scripts, automation, and build verification.
## 📖 Documentation
### Connection Types
#### IP Tunneling
```bash
knxmonitor --connection-type tunneling --host [--port 3671]
```
#### IP Routing (Multicast)
```bash
knxmonitor --connection-type routing [--multicast-address 224.0.23.12]
```
#### USB Interface
```bash
knxmonitor --connection-type usb [--device /dev/ttyUSB0]
```
### Group Address Database
Import group addresses from ETS CSV export:
```bash
knxmonitor --csv-path group_addresses.csv --connection-type routing
```
**CSV Format:**
```csv
"Group address";"Name";"Central function";"Unfiltered";"Description";"DatapointType";"Security"
"0/1/1";"Living Room Light";"Switching";"No";"Main living room lighting";"DPST-1-1";"Auto"
"0/1/2";"Kitchen Light";"Switching";"No";"Kitchen ceiling light";"DPST-1-1";"Auto"
```
### Advanced Configuration
#### Environment Variables
```bash
export KNX_CONNECTION_TYPE=tunneling
export KNX_HOST=192.168.1.100
export KNX_CSV_PATH=/path/to/addresses.csv
export KNX_LOG_LEVEL=Information
```
#### Configuration File
Create `knxmonitor.json`:
```json
{
"ConnectionType": "tunneling",
"Host": "192.168.1.100",
"Port": 3671,
"CsvPath": "group_addresses.csv",
"LogLevel": "Information",
"HealthCheckPort": 8080
}
```
## 🐳 Docker Usage
### Basic Monitoring
```bash
docker run --rm -it --network host \
ghcr.io/metaneutrons/knxmonitor:latest \
--connection-type routing
```
### With Volume Mapping
```bash
docker run --rm -it --network host \
-v $(pwd)/config:/app/config \
ghcr.io/metaneutrons/knxmonitor:latest \
--csv-path /app/config/addresses.csv \
--connection-type tunneling \
--host 192.168.1.100
```
### Docker Compose
```yaml
version: '3.8'
services:
knxmonitor:
image: ghcr.io/metaneutrons/knxmonitor:latest
network_mode: host
volumes:
- ./config:/app/config:ro
command: >
--connection-type routing
--csv-path /app/config/addresses.csv
--health-check-port 8080
restart: unless-stopped
healthcheck:
test: ["CMD", "./KnxMonitor", "--health-check"]
interval: 30s
timeout: 10s
retries: 3
```
## 🛠️ Development
### Prerequisites
- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)
- [Git](https://git-scm.com/)
- [VS Code](https://code.visualstudio.com/) (recommended)
### VS Code Setup (Recommended)
This project includes comprehensive VS Code configuration for optimal development experience:
#### Quick Start
1. Open the project in VS Code
2. Install recommended extensions (VS Code will prompt)
3. **Press Shift+Cmd+B** to build and run the application
4. Use **F5** to debug with breakpoints
#### Key Shortcuts
- **Shift+Cmd+B**: Build and run in router mode (primary development shortcut)
- **Shift+Cmd+R**: Run in IP routing mode
- **Shift+Cmd+T**: Run in IP tunneling mode
- **Shift+Cmd+W**: Watch mode (hot reload)
- **F5**: Debug with breakpoints
- **Cmd+K Cmd+T**: Run tests
See [.vscode/README.md](.vscode/README.md) for complete VS Code documentation.
### Building from Source
```bash
git clone https://github.com/metaneutrons/KnxMonitor.git
cd KnxMonitor
dotnet tool restore
dotnet restore
dotnet build --configuration Release
```
### Git Hooks Setup (Recommended)
For consistent code quality and conventional commits:
```bash
./setup-hooks.sh
```
This installs Git hooks that:
- ✅ Validate conventional commit messages
- ✅ Format code automatically with CSharpier
- ✅ Build project before commits
- ✅ Run tests before pushes
- ✅ Provide commit message templates
### Running Tests
```bash
dotnet test --configuration Release --verbosity normal
```
### Development Environment
```bash
# Run with hot reload
dotnet run --project KnxMonitor -- --connection-type routing --csv-path test.csv
# Debug build
dotnet build --configuration Debug
```
## 📝 License
This project is licensed under the GNU Lesser General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **KNX Association** for the KNX/EIB standard
- **Falcon SDK** for KNX protocol implementation
- **.NET Community** for the excellent framework
- **Contributors** who make this project possible
## 📞 Support
- **Documentation**: [Wiki](https://github.com/metaneutrons/KnxMonitor/wiki)
- **Issues**: [GitHub Issues](https://github.com/metaneutrons/KnxMonitor/issues)
- **Discussions**: [GitHub Discussions](https://github.com/metaneutrons/KnxMonitor/discussions)
---
**Built with ❤️ using .NET 9 and architecture patterns**