Check Device Connection Status

Check if a device (object) with the specified partial UID is currently connected to the system.

Request

GET /api/is-connected

Authentication Required: Must include JWT token in Authorization header.

Required Scope: objects

Query Parameters:

• partial_uid (string, required): The partial UID of the device to check (hex format)

Request Examples

curl -X GET "http://your-server-ip:port/api/is-connected?partial_uid=ABCDEF123456" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

Success (200 OK)

Device Connected:

{
  "partial_uid": "ABCDEF123456",
  "is_connected": true,
  "uid": "AABBCCDDEEFF",
  "signal_level": 4,
  "hw_id": "01",
  "oid": "1234567890"
}

Device Not Connected:

{
  "partial_uid": "ABCDEF123456",
  "is_connected": false,
  "error": "Device not found or not connected"
}

Response Fields

Field	Type	Description
partial_uid	string	The queried partial UID (hex format)
is_connected	boolean	Whether the device is currently connected
uid	string	Full unique identifier (only if connected)
signal_level	integer	Signal strength level 0-10 (only if connected)
hw_id	string	Hardware identifier (only if connected)
oid	string	Object identifier (only if connected)
error	string	Error message (only if is_connected is false)

Error Responses

400 Bad Request (Plain Text)

FIELD_UID_IS_MISSING

401 Unauthorized (Plain Text)

NOT_LOGGED_IN

403 Forbidden (Plain Text)

FORBIDDEN

405 Method Not Allowed (Plain Text)

Method Not Allowed

500 Internal Server Error (Plain Text)

E_1

JSON Error Responses

For some errors, a JSON response may be returned:

{
  "error": "Invalid UID format"
}

{
  "error": "Database connection failed"
}

Usage Examples

Check Single Device Connection

curl -X GET "http://your-server:8080/api/is-connected?partial_uid=ABC123" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript Implementation

async function checkDeviceConnection(partialUid) {
  try {
    const response = await fetch(`/api/is-connected?partial_uid=${partialUid}`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      const error = await response.text();
      throw new Error(`HTTP ${response.status}: ${error}`);
    }
    
    const data = await response.json();
    
    if (data.is_connected) {
      console.log(`Device ${partialUid} is connected:`);
      console.log(`- Full UID: ${data.uid}`);
      console.log(`- Signal Level: ${data.signal_level}`);
      console.log(`- Hardware ID: ${data.hw_id}`);
      console.log(`- OID: ${data.oid}`);
    } else {
      console.log(`Device ${partialUid} is not connected: ${data.error || 'Unknown reason'}`);
    }
    
    return data;
  } catch (error) {
    console.error('Failed to check device connection:', error);
    throw error;
  }
}

Batch Connection Check

async function checkMultipleDevices(partialUids) {
  const results = [];
  
  for (const uid of partialUids) {
    try {
      const result = await checkDeviceConnection(uid);
      results.push({
        partial_uid: uid,
        status: result.is_connected ? 'connected' : 'disconnected',
        data: result
      });
    } catch (error) {
      results.push({
        partial_uid: uid,
        status: 'error',
        error: error.message
      });
    }
  }
  
  return results;
}

// Usage
const deviceUids = ['ABC123', 'DEF456', 'GHI789'];
checkMultipleDevices(deviceUids).then(results => {
  console.log('Connection Status Summary:');
  results.forEach(result => {
    console.log(`${result.partial_uid}: ${result.status}`);
  });
});

Real-time Monitoring

class DeviceMonitor {
  constructor(partialUid, intervalMs = 30000) {
    this.partialUid = partialUid;
    this.interval = intervalMs;
    this.isMonitoring = false;
    this.lastStatus = null;
  }
  
  async startMonitoring(onStatusChange) {
    this.isMonitoring = true;
    
    while (this.isMonitoring) {
      try {
        const status = await checkDeviceConnection(this.partialUid);
        
        // Check if status changed
        if (this.lastStatus === null || 
            this.lastStatus.is_connected !== status.is_connected) {
          onStatusChange(status, this.lastStatus);
        }
        
        this.lastStatus = status;
        
        // Wait before next check
        await new Promise(resolve => setTimeout(resolve, this.interval));
      } catch (error) {
        console.error(`Monitoring error for ${this.partialUid}:`, error);
        // Continue monitoring despite errors
        await new Promise(resolve => setTimeout(resolve, this.interval));
      }
    }
  }
  
  stopMonitoring() {
    this.isMonitoring = false;
  }
}

// Usage
const monitor = new DeviceMonitor('ABC123', 10000); // Check every 10 seconds
monitor.startMonitoring((current, previous) => {
  if (current.is_connected && (!previous || !previous.is_connected)) {
    console.log(`Device ${current.partial_uid} connected!`);
  } else if (!current.is_connected && previous && previous.is_connected) {
    console.log(`Device ${current.partial_uid} disconnected!`);
  }
});

Error Handling

function handleConnectionCheckError(error, response) {
  switch (response.status) {
    case 400:
      if (error === 'FIELD_UID_IS_MISSING') {
        alert('Partial UID is required');
      } else {
        alert('Invalid request format');
      }
      break;
    case 401:
      // Redirect to login
      window.location.href = '/login';
      break;
    case 403:
      alert('You do not have permission to check device connections');
      break;
    case 405:
      alert('Method not allowed');
      break;
    case 500:
      alert('Server error occurred. Please try again later.');
      break;
    default:
      alert(`Unexpected error: ${error}`);
  }
}

Query Parameter Validation

Valid Partial UID Formats

• Hexadecimal string (case-insensitive)
• Examples: ABC123, ABCDEF123456, 1234567890AB

Invalid Formats

• Empty string: Returns FIELD_UID_IS_MISSING
• Non-hex characters: May return JSON error with "Invalid UID format"
• Too short/long UIDs: Validation depends on system configuration

Use Cases

Device Monitoring Dashboard

// Display connection status in a dashboard
function updateDeviceStatus(deviceList) {
  deviceList.forEach(async (device) => {
    const status = await checkDeviceConnection(device.partial_uid);
    
    const statusElement = document.getElementById(`device-${device.partial_uid}`);
    if (status.is_connected) {
      statusElement.className = 'device-status connected';
      statusElement.textContent = `Connected (Signal: ${status.signal_level})`;
    } else {
      statusElement.className = 'device-status disconnected';
      statusElement.textContent = 'Disconnected';
    }
  });
}

Alarm System Integration

// Trigger alerts for disconnected critical devices
async function checkCriticalDevices(criticalUids) {
  for (const uid of criticalUids) {
    const status = await checkDeviceConnection(uid);
    
    if (!status.is_connected) {
      // Send alert notification
      sendAlert(`Critical device ${uid} is disconnected!`);
    }
  }
}

Important Notes

• Scope Required: Users must have the objects scope to access this endpoint
• Mixed Error Formats: Some errors return plain text, others return JSON
• Real-time Data: Connection status reflects current state, not historical data
• Query Parameter Required: The partial_uid parameter is mandatory