fix: update .gitignore to preserve cmd/ source directories and add missing CLI tools
This commit is contained in:
ProtoTess
@@ -0,0 +1,365 @@
|
||||
# ONVIF Camera Diagnostic Utility
|
||||
|
||||
A comprehensive diagnostic tool for collecting detailed information from ONVIF cameras. This utility helps analyze camera capabilities, troubleshoot issues, and generate reports for creating camera-specific tests.
|
||||
|
||||
## Features
|
||||
|
||||
✅ **Comprehensive Testing** - Tests all major ONVIF operations:
|
||||
- Device information and capabilities
|
||||
- Media profiles and streaming
|
||||
- Video encoder configurations
|
||||
- Imaging settings
|
||||
- PTZ status and presets (if available)
|
||||
- System date/time
|
||||
|
||||
✅ **Detailed Reporting** - Generates JSON reports with:
|
||||
- All successful operations with response data
|
||||
- Failed operations with error details
|
||||
- Response times for performance analysis
|
||||
- Structured data ready for test generation
|
||||
|
||||
✅ **Easy to Use** - Simple command-line interface with minimal requirements
|
||||
|
||||
✅ **XML Debugging** - For detailed debugging, see the companion `onvif-xml-capture` utility that captures raw SOAP XML
|
||||
|
||||
✅ **Helpful for**:
|
||||
- Creating camera-specific integration tests
|
||||
- Troubleshooting ONVIF compatibility issues
|
||||
- Analyzing camera capabilities
|
||||
- Debugging connection problems
|
||||
- Documenting camera configurations
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Build from source
|
||||
```bash
|
||||
cd /path/to/go-onvif
|
||||
go build -o onvif-diagnostics ./cmd/onvif-diagnostics/
|
||||
```
|
||||
|
||||
### Option 2: Install globally
|
||||
```bash
|
||||
go install ./cmd/onvif-diagnostics
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://192.168.1.201/onvif/device_service" \
|
||||
-username "service" \
|
||||
-password "Service.1234"
|
||||
```
|
||||
|
||||
### With XML Capture (for debugging)
|
||||
```bash
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://192.168.1.201/onvif/device_service" \
|
||||
-username "service" \
|
||||
-password "Service.1234" \
|
||||
-capture-xml \
|
||||
-verbose
|
||||
```
|
||||
|
||||
This creates two files:
|
||||
- `Manufacturer_Model_Firmware_timestamp.json` - Diagnostic report
|
||||
- `Manufacturer_Model_Firmware_xmlcapture_timestamp.tar.gz` - Raw SOAP XML archive
|
||||
|
||||
### Verbose Output
|
||||
```bash
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://192.168.1.201/onvif/device_service" \
|
||||
-username "service" \
|
||||
-password "Service.1234" \
|
||||
-verbose
|
||||
```
|
||||
|
||||
### Capture Raw SOAP XML
|
||||
```bash
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://192.168.1.201/onvif/device_service" \
|
||||
-username "service" \
|
||||
-password "Service.1234" \
|
||||
-capture-xml
|
||||
```
|
||||
|
||||
Enables XML traffic capture and creates a compressed tar.gz archive containing all SOAP request/response pairs. Useful for debugging XML parsing issues or analyzing camera behavior.
|
||||
|
||||
The archive contains:
|
||||
- `capture_001_GetDeviceInformation.json` - Request/response metadata with operation name
|
||||
- `capture_001_GetDeviceInformation_request.xml` - Formatted SOAP request
|
||||
- `capture_001_GetDeviceInformation_response.xml` - Formatted SOAP response
|
||||
- `capture_002_GetSystemDateAndTime.json` - Next operation metadata
|
||||
- ... (one set per SOAP operation, named by operation type)
|
||||
|
||||
Each file is named with the SOAP operation (e.g., GetDeviceInformation, GetProfiles) for easy identification.
|
||||
|
||||
Extract the archive:
|
||||
```bash
|
||||
tar -xzf camera-logs/Camera_Model_xmlcapture_timestamp.tar.gz
|
||||
```
|
||||
|
||||
### Custom Output Directory
|
||||
```bash
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://192.168.1.201/onvif/device_service" \
|
||||
-username "service" \
|
||||
-password "Service.1234" \
|
||||
-output ./my-camera-reports
|
||||
```
|
||||
|
||||
### All Options
|
||||
```
|
||||
Usage of ./onvif-diagnostics:
|
||||
-endpoint string
|
||||
ONVIF device endpoint (e.g., http://192.168.1.201/onvif/device_service)
|
||||
-username string
|
||||
ONVIF username
|
||||
-password string
|
||||
ONVIF password
|
||||
-output string
|
||||
Output directory for logs (default "./camera-logs")
|
||||
-timeout int
|
||||
Request timeout in seconds (default 30)
|
||||
-verbose
|
||||
Verbose output
|
||||
-include-raw
|
||||
Include raw SOAP responses (increases file size)
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
ONVIF Camera Diagnostic Utility v1.0.0
|
||||
========================================
|
||||
|
||||
Starting diagnostic collection...
|
||||
|
||||
→ 1. Getting device information...
|
||||
✓ Manufacturer: Bosch, Model: FLEXIDOME indoor 5100i IR
|
||||
→ 2. Getting system date and time...
|
||||
✓ Retrieved
|
||||
→ 3. Getting capabilities...
|
||||
✓ Services: Device, Media, Imaging, Events, Analytics
|
||||
→ 4. Discovering service endpoints...
|
||||
✓ Service endpoints discovered
|
||||
→ 5. Getting media profiles...
|
||||
✓ Found 4 profile(s)
|
||||
→ 6. Getting stream URIs for all profiles...
|
||||
✓ Retrieved 4/4 stream URIs
|
||||
→ 7. Getting snapshot URIs for all profiles...
|
||||
✓ Retrieved 4/4 snapshot URIs
|
||||
→ 8. Getting video encoder configurations...
|
||||
✓ Retrieved 4/4 video encoder configs
|
||||
→ 9. Getting imaging settings...
|
||||
✓ Retrieved 1/1 imaging settings
|
||||
→ 10. Getting PTZ status...
|
||||
ℹ No PTZ configurations found
|
||||
→ 11. Getting PTZ presets...
|
||||
ℹ No PTZ configurations found
|
||||
→ Saving diagnostic report...
|
||||
|
||||
========================================
|
||||
✓ Diagnostic collection complete!
|
||||
Report saved to: camera-logs/Bosch_FLEXIDOME_indoor_5100i_IR_8.71.0066_20251107-193656.json
|
||||
Total errors: 0
|
||||
|
||||
Device: Bosch FLEXIDOME indoor 5100i IR
|
||||
Firmware: 8.71.0066
|
||||
Profiles: 4
|
||||
|
||||
Please share this file for analysis and test creation.
|
||||
========================================
|
||||
```
|
||||
|
||||
## Report Structure
|
||||
|
||||
The generated JSON report includes:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-11-07T19:36:56Z",
|
||||
"utility_version": "1.0.0",
|
||||
"connection_info": {
|
||||
"endpoint": "http://192.168.1.201/onvif/device_service",
|
||||
"username": "service",
|
||||
"test_date": "2025-11-07"
|
||||
},
|
||||
"device_info": {
|
||||
"success": true,
|
||||
"data": {
|
||||
"manufacturer": "Bosch",
|
||||
"model": "FLEXIDOME indoor 5100i IR",
|
||||
"firmware_version": "8.71.0066",
|
||||
"serial_number": "404754734001050102",
|
||||
"hardware_id": "F000B543"
|
||||
},
|
||||
"response_time": "21.5ms"
|
||||
},
|
||||
"profiles": {
|
||||
"success": true,
|
||||
"count": 4,
|
||||
"data": [ /* profile details */ ]
|
||||
},
|
||||
"stream_uris": [ /* stream URI results for each profile */ ],
|
||||
"errors": [ /* any errors encountered */ ]
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Creating Camera-Specific Tests
|
||||
Run the diagnostic on your camera and share the JSON file. The report contains all the information needed to create comprehensive integration tests.
|
||||
|
||||
### 2. Troubleshooting Connection Issues
|
||||
If your camera isn't working, run diagnostics to see exactly which operations fail and what error messages are returned.
|
||||
|
||||
### 3. Comparing Cameras
|
||||
Run diagnostics on multiple cameras to compare capabilities, response times, and compatibility.
|
||||
|
||||
### 4. Documentation
|
||||
Generate detailed reports of camera configurations for documentation purposes.
|
||||
|
||||
## Interpreting Results
|
||||
|
||||
### Success Indicators
|
||||
- ✓ Green checkmarks indicate successful operations
|
||||
- Response times help identify performance issues
|
||||
- High success rates indicate good compatibility
|
||||
|
||||
### Error Indicators
|
||||
- ✗ Red X marks indicate failed operations
|
||||
- ℹ Info symbols indicate optional features not available
|
||||
- Check the `errors` array in JSON for detailed error messages
|
||||
|
||||
### Common Issues
|
||||
|
||||
**All operations fail:**
|
||||
- Check network connectivity
|
||||
- Verify endpoint URL is correct
|
||||
- Ensure camera is powered on
|
||||
|
||||
**Authentication errors:**
|
||||
- Verify username and password
|
||||
- Check user permissions on camera
|
||||
|
||||
**Some profiles fail:**
|
||||
- Camera may have different capabilities per profile
|
||||
- Some operations may not be supported by all profiles
|
||||
|
||||
**Timeout errors:**
|
||||
- Increase timeout with `-timeout 60`
|
||||
- Check network latency
|
||||
- Verify camera is responding
|
||||
|
||||
## Sharing Reports
|
||||
|
||||
When sharing diagnostic reports:
|
||||
|
||||
1. **Anonymize if needed** - The report includes:
|
||||
- IP addresses (in endpoint)
|
||||
- Usernames (not passwords)
|
||||
- Serial numbers
|
||||
|
||||
2. **What to share**:
|
||||
- The complete JSON file
|
||||
- Any console output showing errors
|
||||
- Camera model and firmware version
|
||||
|
||||
3. **Where to share**:
|
||||
- GitHub Issues
|
||||
- Email for analysis
|
||||
- Pull request descriptions
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Batch Testing Multiple Cameras
|
||||
Create a script to test multiple cameras:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
cameras=(
|
||||
"192.168.1.201:service:password1"
|
||||
"192.168.1.202:admin:password2"
|
||||
"192.168.1.203:user:password3"
|
||||
)
|
||||
|
||||
for camera in "${cameras[@]}"; do
|
||||
IFS=':' read -r ip user pass <<< "$camera"
|
||||
echo "Testing camera at $ip..."
|
||||
./onvif-diagnostics \
|
||||
-endpoint "http://$ip/onvif/device_service" \
|
||||
-username "$user" \
|
||||
-password "$pass"
|
||||
done
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
Include in CI/CD pipelines:
|
||||
|
||||
```yaml
|
||||
- name: Run ONVIF Diagnostics
|
||||
run: |
|
||||
./onvif-diagnostics \
|
||||
-endpoint "${{ secrets.CAMERA_ENDPOINT }}" \
|
||||
-username "${{ secrets.CAMERA_USERNAME }}" \
|
||||
-password "${{ secrets.CAMERA_PASSWORD }}" \
|
||||
-output ./reports
|
||||
|
||||
- name: Upload Diagnostic Reports
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: camera-diagnostics
|
||||
path: ./reports/
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Adding New Tests
|
||||
|
||||
To add new diagnostic tests, edit `cmd/onvif-diagnostics/main.go`:
|
||||
|
||||
1. Create a new test function following the pattern:
|
||||
```go
|
||||
func testNewOperation(ctx context.Context, client *onvif.Client, report *CameraReport) *NewOperationResult {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
2. Add result struct to store data
|
||||
3. Call the test in main()
|
||||
4. Update report structure
|
||||
|
||||
### Building for Different Platforms
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
GOOS=linux GOARCH=amd64 go build -o onvif-diagnostics-linux ./cmd/onvif-diagnostics/
|
||||
|
||||
# Windows
|
||||
GOOS=windows GOARCH=amd64 go build -o onvif-diagnostics.exe ./cmd/onvif-diagnostics/
|
||||
|
||||
# macOS ARM
|
||||
GOOS=darwin GOARCH=arm64 go build -o onvif-diagnostics-mac-arm ./cmd/onvif-diagnostics/
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Same as parent project.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Run diagnostics with `-verbose` flag
|
||||
2. Share the generated JSON report
|
||||
3. **For XML parsing issues**: Use `onvif-xml-capture` utility to capture raw SOAP XML
|
||||
4. Open a GitHub issue with the report attached
|
||||
|
||||
## Related Tools
|
||||
|
||||
- **onvif-xml-capture** - Captures raw SOAP XML requests/responses for detailed debugging
|
||||
- Location: `cmd/onvif-xml-capture/`
|
||||
- Use when: Diagnostic report shows errors and you need to see raw XML
|
||||
- See: `XML_DEBUGGING_SOLUTION.md` for complete guide
|
||||
|
||||
Reference in New Issue
Block a user