Session Monitoring

This section covers session monitoring operations in the Rosepetal API for tracking real-time data collection and monitoring workflows.

Overview

Sessions represent active monitoring periods where images are collected from cameras or sensors. The API provides endpoints to query session status, retrieve session data, and monitor real-time flows.

Session Structure

Each monitoring session contains the following properties:

Field	Type	Description
start	timestamp	Session start time
stop	timestamp	Session end time (if completed)
monitor	reference	Associated monitor/camera reference
data	object	Session metadata and counters
flow	object	Real-time data flow information
uid	string	User identifier who started session

Monitor Status Operations

Start Monitoring Session

Initiate a new monitoring session for a specific monitor.

GET /monitor/{monitor_id}/start

Parameters:

Parameter	Type	Description
monitor_id	string	Unique monitor identifier
uid	string (optional)	User ID starting the session

Example Request:

GET /monitor/camera-production-line-1/start?uid=user123

Response (Success):

{
  "data": {
    "result": "Started",
    "error": false
  }
}

Response (Already Running):

{
  "data": {
    "result": "Error: Already started",
    "error": true
  }
}

Stop Monitoring Session

End the current monitoring session and finalize session data.

GET /monitor/{monitor_id}/stop

Parameters:

Parameter	Type	Description
monitor_id	string	Unique monitor identifier

Example Request:

GET /monitor/camera-production-line-1/stop

Response (Success):

{
  "data": {
    "result": "Stopped",
    "error": false
  }
}

Response (Already Stopped):

{
  "data": {
    "error": true,
    "result": "Error: already stopped"
  }
}

Session Data Structure

Session Metadata

When a session is created, it includes:

{
  "start": "2024-01-15T10:00:00Z",
  "monitor": "monitor/camera-production-line-1",
  "data": {
    "controller": {
      "action": {
        "status": true,
        "request": {
          "command": "start_capture",
          "params": {}
        }
      }
    },
    "totalCounter": 0
  },
  "flow": {},
  "uid": "user123"
}

Real-time Monitor State

During an active session, the monitor maintains real-time state:

{
  "status": true,
  "session": "session_id_123",
  "image": {
    "imageData": "base64_thumbnail_data"
  },
  "totalCounter": 45,
  "flow": {
    "current_flow_rate": 12.5,
    "total_processed": 45
  },
  "controller": {
    "action": {
      "status": false
    }
  }
}

Monitor State Fields

Field	Type	Description
status	boolean	Whether monitor is actively collecting
session	string	Current session ID (empty when stopped)
totalCounter	number	Total images captured this session
image	object	Latest captured image data
flow	object	Real-time processing metrics
controller	object	Hardware controller state

Image Upload During Sessions

Images captured during monitoring sessions are automatically uploaded:

POST /monitor/{monitor_id}/image

Request Body:

{
  "image": "base64_encoded_image_data",
  "image_data": {
    "date": 1642248000000,
    "name": "capture_001.png",
    "dataset": "production_dataset_id",
    "tag": "normal"
  }
}

Response:

{
  "data": {
    "error": false,
    "result": "Added image",
    "id": "image_doc_id_123"
  }
}

Tag Updates During Sessions

Update image annotations in real-time during monitoring:

POST /monitor/updateTags

Request Body:

{
  "dataset": "production_dataset_id",
  "imageID": "image_doc_id_123",
  "tags": [
    {
      "tag": "defect_type_1",
      "x": 0.1,
      "y": 0.2,
      "w": 0.3,
      "h": 0.4
    }
  ]
}

Response:

{
  "error": false,
  "status": "success"
}

Session Lifecycle

1. Session Initialization

• Monitor status set to true
• New session document created in Firestore
• Real-time database references initialized
• Counters reset to zero

2. Active Monitoring

• Images captured and uploaded automatically
• Real-time counters updated
• Flow metrics tracked
• Annotations processed

3. Session Termination

• Monitor status set to false
• Session end time recorded
• Final counters saved
• Training status reset

Querying Session Data

Get Session History

// Query completed sessions for a monitor
const sessions = await firestore
  .collection('session')
  .where('monitor', '==', firestore.doc('monitor/camera-1'))
  .where('stop', '!=', null)
  .orderBy('start', 'desc')
  .limit(10)
  .get();

sessions.forEach(doc => {
  const session = doc.data();
  console.log(`Session ${doc.id}:`);
  console.log(`Duration: ${session.stop - session.start}ms`);
  console.log(`Images: ${session.data.totalCounter}`);
});

Monitor Current Status

// Check if monitor is currently active
const monitorRef = database.ref('monitor/camera-1');
const status = await monitorRef.once('value');
const isActive = status.val()?.status === true;
console.log(`Monitor active: ${isActive}`);

Error Handling

Session Management Errors

Monitor Not Found

{
  "data": {
    "error": true,
    "result": "Monitor not found or access denied"
  }
}

Image Upload Errors

{
  "data": {
    "error": true,
    "result": "Error: image not found"
  }
}

Tag Update Errors

{
  "error": "Failed to update tags",
  "details": "Dataset reference invalid"
}

Best Practices

Session Management

• Always stop sessions when monitoring is complete
• Monitor session duration to prevent resource leaks
• Use meaningful UIDs to track session ownership

Image Processing

• Implement proper error handling for image uploads
• Monitor storage quotas during long sessions
• Validate image data before processing

Real-time Monitoring

• Poll monitor status periodically (max 1Hz)
• Implement connection retry logic
• Handle network interruptions gracefully

Integration Examples

Start/Stop Monitoring Workflow

async function startMonitoringWorkflow(monitorId, userId) {
  try {
    // Start monitoring
    const startResp = await fetch(`/monitor/${monitorId}/start?uid=${userId}`);
    const startData = await startResp.json();

    if (startData.data.error) {
      throw new Error(startData.data.result);
    }

    console.log('Monitoring started successfully');

    // Monitor for duration...
    await new Promise(resolve => setTimeout(resolve, 30000));

    // Stop monitoring
    const stopResp = await fetch(`/monitor/${monitorId}/stop`);
    const stopData = await stopResp.json();

    console.log('Monitoring stopped:', stopData.data.result);

  } catch (error) {
    console.error('Monitoring workflow error:', error);
  }
}