feat: Geutebruck GeViScope/GeViSoft Action Mapping System - MVP
This MVP release provides a complete full-stack solution for managing action mappings in Geutebruck's GeViScope and GeViSoft video surveillance systems. ## Features ### Flutter Web Application (Port 8081) - Modern, responsive UI for managing action mappings - Action picker dialog with full parameter configuration - Support for both GSC (GeViScope) and G-Core server actions - Consistent UI for input and output actions with edit/delete capabilities - Real-time action mapping creation, editing, and deletion - Server categorization (GSC: prefix for GeViScope, G-Core: prefix for G-Core servers) ### FastAPI REST Backend (Port 8000) - RESTful API for action mapping CRUD operations - Action template service with comprehensive action catalog (247 actions) - Server management (G-Core and GeViScope servers) - Configuration tree reading and writing - JWT authentication with role-based access control - PostgreSQL database integration ### C# SDK Bridge (gRPC, Port 50051) - Native integration with GeViSoft SDK (GeViProcAPINET_4_0.dll) - Action mapping creation with correct binary format - Support for GSC and G-Core action types - Proper Camera parameter inclusion in action strings (fixes CrossSwitch bug) - Action ID lookup table with server-specific action IDs - Configuration reading/writing via SetupClient ## Bug Fixes - **CrossSwitch Bug**: GSC and G-Core actions now correctly display camera/PTZ head parameters in GeViSet - Action strings now include Camera parameter: `@ PanLeft (Comment: "", Camera: 101028)` - Proper filter flags and VideoInput=0 for action mappings - Correct action ID assignment (4198 for GSC, 9294 for G-Core PanLeft) ## Technical Stack - **Frontend**: Flutter Web, Dart, Dio HTTP client - **Backend**: Python FastAPI, PostgreSQL, Redis - **SDK Bridge**: C# .NET 8.0, gRPC, GeViSoft SDK - **Authentication**: JWT tokens - **Configuration**: GeViSoft .set files (binary format) ## Credentials - GeViSoft/GeViScope: username=sysadmin, password=masterkey - Default admin: username=admin, password=admin123 ## Deployment All services run on localhost: - Flutter Web: http://localhost:8081 - FastAPI: http://localhost:8000 - SDK Bridge gRPC: localhost:50051 - GeViServer: localhost (default port) Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Administrator
438
API_ENDPOINTS_GUIDE.md
Normal file
438
API_ENDPOINTS_GUIDE.md
Normal file
@@ -0,0 +1,438 @@
|
||||
# Action Mappings REST API - Complete Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The REST API now provides comprehensive access to action mappings from GeViSoft .set files. You can access all endpoints via **Swagger UI** at: `http://localhost:8000/docs`
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication:
|
||||
- **Username:** `admin`
|
||||
- **Password:** `admin123`
|
||||
|
||||
Click the **"Authorize"** button in Swagger UI to log in.
|
||||
|
||||
## Available Endpoints
|
||||
|
||||
### 1. GET /api/v1/configuration/action-mappings/export
|
||||
|
||||
**Get all action mappings (READ)**
|
||||
|
||||
Returns complete list of all action mappings with structured format including parameters.
|
||||
|
||||
**Authentication:** Viewer role (all users)
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"total_mappings": 51,
|
||||
"mappings_with_parameters": 11,
|
||||
"mappings": [
|
||||
{
|
||||
"id": 1,
|
||||
"offset": 252173,
|
||||
"name": null,
|
||||
"input_actions": [],
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "CrossSwitch C_101027 -> M",
|
||||
"parameters": {
|
||||
"SwitchMode": "True",
|
||||
"VideoInput": "101027",
|
||||
"VideoOutput": ""
|
||||
}
|
||||
},
|
||||
{
|
||||
"action": "GSC ViewerConnectLive V <- C",
|
||||
"parameters": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Use Case:**
|
||||
- Display all mappings in your frontend
|
||||
- Export to Excel/CSV
|
||||
- Analysis and reporting
|
||||
|
||||
---
|
||||
|
||||
### 2. GET /api/v1/configuration/action-mappings/{mapping_id}
|
||||
|
||||
**Get single mapping by ID (READ)**
|
||||
|
||||
Retrieve details of a specific action mapping.
|
||||
|
||||
**Authentication:** Viewer role
|
||||
|
||||
**Path Parameters:**
|
||||
- `mapping_id`: Integer (1-based index, e.g., 1 = first mapping, 2 = second mapping)
|
||||
|
||||
**Example Request:**
|
||||
```
|
||||
GET /api/v1/configuration/action-mappings/5
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": 5,
|
||||
"offset": 253586,
|
||||
"name": null,
|
||||
"input_actions": [],
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "GSC warning: demo mode for 80 min",
|
||||
"parameters": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Use Case:**
|
||||
- View details of specific mapping
|
||||
- Editing preparation
|
||||
- Debugging
|
||||
|
||||
---
|
||||
|
||||
### 3. POST /api/v1/configuration/action-mappings
|
||||
|
||||
**Create new mapping (CREATE)** ⚠️ Coming Soon
|
||||
|
||||
Add a new action mapping to the configuration.
|
||||
|
||||
**Authentication:** Administrator role
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Switch Camera 101027",
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "CrossSwitch C_101027 -> M",
|
||||
"parameters": {
|
||||
"SwitchMode": "True",
|
||||
"VideoInput": "101027"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Status:** HTTP 501 Not Implemented
|
||||
**Reason:** Requires .set file writer implementation (planned for next phase)
|
||||
|
||||
---
|
||||
|
||||
### 4. PUT /api/v1/configuration/action-mappings/{mapping_id}
|
||||
|
||||
**Update existing mapping (UPDATE)** ⚠️ Coming Soon
|
||||
|
||||
Modify an existing action mapping.
|
||||
|
||||
**Authentication:** Administrator role
|
||||
|
||||
**Path Parameters:**
|
||||
- `mapping_id`: ID of mapping to update
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "CrossSwitch C_101027 -> M",
|
||||
"parameters": {
|
||||
"SwitchMode": "True",
|
||||
"VideoInput": "101027",
|
||||
"VideoOutput": "2"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Status:** HTTP 501 Not Implemented
|
||||
|
||||
---
|
||||
|
||||
### 5. DELETE /api/v1/configuration/action-mappings/{mapping_id}
|
||||
|
||||
**Delete mapping (DELETE)** ⚠️ Coming Soon
|
||||
|
||||
Remove an action mapping from configuration.
|
||||
|
||||
**Authentication:** Administrator role
|
||||
|
||||
**Path Parameters:**
|
||||
- `mapping_id`: ID of mapping to delete
|
||||
|
||||
**Status:** HTTP 501 Not Implemented
|
||||
|
||||
---
|
||||
|
||||
### 6. POST /api/v1/configuration/action-mappings/bulk-import
|
||||
|
||||
**Bulk import from Excel/CSV (CREATE MANY)** ⚠️ Coming Soon
|
||||
|
||||
Import multiple action mappings at once.
|
||||
|
||||
**Authentication:** Administrator role
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"mappings": [
|
||||
{
|
||||
"name": "Mapping 1",
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "Action1",
|
||||
"parameters": {"param1": "value1"}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "Mapping 2",
|
||||
"output_actions": [
|
||||
{
|
||||
"action": "Action2",
|
||||
"parameters": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"replace_existing": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully imported 100 action mappings",
|
||||
"imported_count": 100,
|
||||
"failed_count": 0,
|
||||
"errors": []
|
||||
}
|
||||
```
|
||||
|
||||
**Status:** HTTP 501 Not Implemented
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
### ✅ Fully Functional
|
||||
- **GET /action-mappings/export** - Read all mappings
|
||||
- **GET /action-mappings/{id}** - Read single mapping
|
||||
|
||||
### ⏳ Planned (Next Phase)
|
||||
- **POST /action-mappings** - Create single mapping
|
||||
- **PUT /action-mappings/{id}** - Update mapping
|
||||
- **DELETE /action-mappings/{id}** - Delete mapping
|
||||
- **POST /action-mappings/bulk-import** - Bulk import
|
||||
|
||||
## Frontend Integration Recommendations
|
||||
|
||||
### Phase 1: Read-Only Interface (Available Now)
|
||||
|
||||
Build your frontend to:
|
||||
|
||||
1. **Display all mappings**
|
||||
```javascript
|
||||
// Fetch all mappings
|
||||
GET /api/v1/configuration/action-mappings/export
|
||||
|
||||
// Display in table/grid
|
||||
- Column: ID
|
||||
- Column: Actions (list)
|
||||
- Column: Parameters (expandable)
|
||||
- Column: Offset (for debugging)
|
||||
```
|
||||
|
||||
2. **View details**
|
||||
```javascript
|
||||
// User clicks on mapping
|
||||
GET /api/v1/configuration/action-mappings/{id}
|
||||
|
||||
// Show modal/detail view with:
|
||||
- All actions
|
||||
- All parameters
|
||||
- Formatted display
|
||||
```
|
||||
|
||||
3. **Export to Excel**
|
||||
```javascript
|
||||
// Get all mappings
|
||||
const data = await fetch('/api/v1/configuration/action-mappings/export')
|
||||
|
||||
// Convert to Excel using library (e.g., xlsx, exceljs)
|
||||
// Each mapping = 1 row
|
||||
// Columns: ID, Actions (comma-separated), Parameters (JSON)
|
||||
```
|
||||
|
||||
### Phase 2: Full CRUD (Coming Soon)
|
||||
|
||||
Once the .set file writer is implemented:
|
||||
|
||||
1. **Manual Add**
|
||||
```javascript
|
||||
// User fills form
|
||||
POST /api/v1/configuration/action-mappings
|
||||
Body: { name, output_actions }
|
||||
```
|
||||
|
||||
2. **Edit**
|
||||
```javascript
|
||||
// User modifies mapping
|
||||
PUT /api/v1/configuration/action-mappings/{id}
|
||||
Body: { output_actions }
|
||||
```
|
||||
|
||||
3. **Delete**
|
||||
```javascript
|
||||
DELETE /api/v1/configuration/action-mappings/{id}
|
||||
```
|
||||
|
||||
4. **Bulk Import from Excel**
|
||||
```javascript
|
||||
// User uploads Excel file
|
||||
// Parse Excel rows into JSON array
|
||||
// Post to bulk import endpoint
|
||||
POST /api/v1/configuration/action-mappings/bulk-import
|
||||
Body: { mappings: [...], replace_existing: false }
|
||||
```
|
||||
|
||||
## Example Excel Import Workflow
|
||||
|
||||
### Excel Format
|
||||
|
||||
| ID | Name | Action 1 | Param 1 Name | Param 1 Value | Action 2 | Param 2 Name | Param 2 Value |
|
||||
|----|------|----------|--------------|---------------|----------|--------------|---------------|
|
||||
| 1 | Switch Cam 1 | CrossSwitch C_101027 -> M | SwitchMode | True | ViewerConnect | ClientID | 123 |
|
||||
| 2 | Switch Cam 2 | CrossSwitch C_101028 -> M | SwitchMode | True | ViewerConnect | ClientID | 124 |
|
||||
|
||||
### Frontend Processing
|
||||
|
||||
```javascript
|
||||
async function importExcel(file) {
|
||||
// 1. Parse Excel (using library like xlsx)
|
||||
const workbook = XLSX.read(await file.arrayBuffer());
|
||||
const sheet = workbook.Sheets[workbook.SheetNames[0]];
|
||||
const rows = XLSX.utils.sheet_to_json(sheet);
|
||||
|
||||
// 2. Convert to API format
|
||||
const mappings = rows.map(row => ({
|
||||
name: row.Name,
|
||||
output_actions: [
|
||||
{
|
||||
action: row['Action 1'],
|
||||
parameters: {
|
||||
[row['Param 1 Name']]: row['Param 1 Value']
|
||||
}
|
||||
}
|
||||
]
|
||||
}));
|
||||
|
||||
// 3. Post to API
|
||||
const response = await fetch('/api/v1/configuration/action-mappings/bulk-import', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${token}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
mappings,
|
||||
replace_existing: false
|
||||
})
|
||||
});
|
||||
|
||||
const result = await response.json();
|
||||
console.log(`Imported: ${result.imported_count}, Failed: ${result.failed_count}`);
|
||||
}
|
||||
```
|
||||
|
||||
## Testing in Swagger UI
|
||||
|
||||
1. Open: `http://localhost:8000/docs`
|
||||
|
||||
2. Click **"Authorize"**
|
||||
- Username: `admin`
|
||||
- Password: `admin123`
|
||||
|
||||
3. Try the **GET** endpoints:
|
||||
- Expand `GET /api/v1/configuration/action-mappings/export`
|
||||
- Click "Try it out"
|
||||
- Click "Execute"
|
||||
- See all 51+ mappings with parameters!
|
||||
|
||||
4. Try single mapping:
|
||||
- Expand `GET /api/v1/configuration/action-mappings/{mapping_id}`
|
||||
- Click "Try it out"
|
||||
- Enter `1` for mapping_id
|
||||
- Click "Execute"
|
||||
- See first mapping details
|
||||
|
||||
5. Try CREATE (will show 501):
|
||||
- Expand `POST /api/v1/configuration/action-mappings`
|
||||
- Click "Try it out"
|
||||
- See example request body
|
||||
- Click "Execute"
|
||||
- Get 501 Not Implemented (expected - coming soon!)
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (You Can Do Now)
|
||||
|
||||
✅ Build frontend that:
|
||||
- Displays all mappings (GET /export)
|
||||
- Shows mapping details (GET /{id})
|
||||
- Exports to Excel for editing
|
||||
- Plans Excel import format
|
||||
|
||||
### Coming Soon (I Will Implement)
|
||||
|
||||
🔧 C# .set file writer to enable:
|
||||
- POST /action-mappings (create)
|
||||
- PUT /action-mappings/{id} (update)
|
||||
- DELETE /action-mappings/{id} (delete)
|
||||
- POST /action-mappings/bulk-import (Excel import)
|
||||
|
||||
### Future Expansion
|
||||
|
||||
📈 Additional configuration sections:
|
||||
- Cameras
|
||||
- Monitors
|
||||
- Digital I/O
|
||||
- Alarms
|
||||
- System settings
|
||||
|
||||
---
|
||||
|
||||
## API Schema Summary
|
||||
|
||||
All endpoints return structured data with:
|
||||
|
||||
```typescript
|
||||
interface ActionMapping {
|
||||
id: number; // Sequential ID (1-based)
|
||||
offset: number; // Byte offset in .set file
|
||||
name?: string; // Optional descriptive name
|
||||
input_actions: Action[]; // Trigger actions (currently empty)
|
||||
output_actions: Action[]; // Response actions (at least 1)
|
||||
}
|
||||
|
||||
interface Action {
|
||||
action: string; // Action command
|
||||
parameters: Record<string, string>; // Parameter name-value pairs
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Ready to start building your frontend!** 🚀
|
||||
|
||||
All READ operations are fully functional. CREATE/UPDATE/DELETE coming in next phase once .set file writer is complete.
|
||||
Reference in New Issue
Block a user