Device Management

Timesheet supports dedicated kiosk devices for employee time tracking, providing secure, location-based clock-in/out functionality. The device management system handles device registration, activation, monitoring, and security.

Overview

The device management system provides:

• Device Registration - Admin registration of kiosk devices
• Activation Process - Secure device activation with time-limited codes
• Kiosk Mode - Full-screen clock interface for shared devices
• Location Binding - Devices tied to specific work locations
• Usage Monitoring - Track device usage and employee activity
• Security Management - Device revocation and access control

Key Features

Secure Device Registration

• Admin-controlled device registration
• Unique device identifiers and activation codes
• Location-based device assignment
• Time-limited activation codes for security

Kiosk Mode Interface

• Full-screen clock-in/out interface
• Touch-optimised for tablet and kiosk hardware
• Automatic logout and security features
• Offline capability with sync when online

Device Monitoring

• Real-time device status tracking
• Usage statistics and analytics
• Last activity monitoring
• Device health and connectivity status

Location Integration

• Devices bound to specific locations
• Automatic location detection for timesheets
• Geofencing integration
• Location-based employee filtering

Device Data Structure

Device Schema

interface IDevice {
  deviceId?: string           // Unique device identifier (set during activation)
  deviceName: string          // Admin-friendly name
  locationName: string        // Associated location name
  locationAddress?: string    // Physical address
  status: "active" | "disabled" | "revoked"
  registeredBy: ObjectId      // Admin who registered device
  registeredAt: Date          // Registration timestamp
  lastActivity: Date          // Last usage timestamp
  lastUsedBy?: ObjectId       // Last employee who used device
  totalPunches: number        // Usage counter
  activationCode?: string     // One-time activation code
  activationCodeExpiry?: Date // Activation code expiry
  revocationReason?: string   // Reason for revocation
  revokedAt?: Date           // Revocation timestamp
  revokedBy?: ObjectId       // Admin who revoked device
}

Device Status Types

Device Registration Process

1. Admin Registration

Administrators register devices through the admin interface:

POST /api/devices
Content-Type: application/json

{
  "deviceName": "Kiosk 1 - Head Office",
  "locationName": "Head Office",
  "locationAddress": "123 Collins Street, Melbourne VIC 3000"
}

Response:

{
  "device": {
    "id": "device_id",
    "deviceName": "Kiosk 1 - Head Office",
    "locationName": "Head Office",
    "locationAddress": "123 Collins Street, Melbourne VIC 3000",
    "status": "active",
    "activationCode": "ABC123",
    "activationCodeExpiry": "2024-01-15T23:59:59Z",
    "registeredAt": "2024-01-01T10:00:00Z"
  }
}

2. Device Activation

Devices must be activated using the provided activation code:

1. Access Activation URL

   • Navigate to device activation page
   • Enter activation code provided by admin

2. Device Identification

   • System generates unique device ID
   • Links device to location and settings
   • Stores device fingerprint for security

3. Activation Completion

   • Device marked as activated
   • Activation code invalidated
   • Device ready for employee use

3. Device Configuration

After activation, devices can be configured:

• Display Settings - Screen timeout, brightness
• Security Settings - Auto-logout timer, PIN attempts
• Location Settings - Geofencing parameters
• Photo Settings - Camera quality, face detection

Kiosk Mode Interface

Full-Screen Experience

Kiosk mode provides a dedicated clock interface:

• Full-screen display - No browser chrome or navigation
• Touch-optimised - Large buttons and touch targets
• Auto-rotation - Supports portrait and landscape
• Screensaver - Automatic screensaver with company branding

Security Features

Automatic Logout

• Idle Timeout - Automatic logout after 30 seconds of inactivity
• Visual Countdown - Circular progress indicator showing remaining time
• Immediate Logout - Manual logout button always available
• Session Clearing - Complete session data cleared on logout

Access Control

• PIN-Only Access - No keyboard input for security
• Failed Attempt Limiting - Temporary lockout after failed attempts
• Admin Override - Emergency admin access codes
• Device Binding - Tied to specific device hardware

Interface Components

PIN Entry Screen

• Numeric Keypad - Large, touch-friendly number buttons
• PIN Display - Masked PIN entry with visual feedback
• Clear/Backspace - Easy PIN correction
• Employee Lookup - Real-time employee validation

Clock Interface

• Employee Information - Name, role, location display
• Current Time - Large, prominent time display
• Action Buttons - Clock In, Break, Clock Out buttons
• Status Indicators - Current clock status and last actions
• Photo Capture - Integrated camera for face detection

Success/Error Screens

• Success Animation - Visual confirmation of successful actions
• Error Messages - Clear error descriptions and solutions
• Retry Options - Easy retry for failed operations
• Help Information - Contact details for assistance

Device Activation Process

Activation Code Generation

When a device is registered, the system generates:

• Unique Code - 6-character alphanumeric code
• Time Limit - 24-hour expiry for security
• Single Use - Code invalidated after successful activation
• Admin Notification - Email with activation instructions

Activation Steps

Step 1: Access Activation Page

https://timesheet.company.com/device/activate

Step 2: Enter Activation Code

• Enter 6-character code provided by admin
• System validates code and expiry
• Device fingerprinting for security

Step 3: Device Configuration

• Set device name and location
• Configure display and security settings
• Test camera and location services

Step 4: Activation Completion

• Generate unique device ID
• Store device configuration
• Mark device as active and ready

Activation Security

Device Fingerprinting

• Browser Fingerprint - Unique browser/device identification
• Hardware Detection - Screen resolution, capabilities
• Network Information - IP address and location
• Persistent Storage - Local storage for device identity

Code Security

• Time-Limited - Codes expire after 24 hours
• Single Use - Codes invalidated after activation
• Secure Generation - Cryptographically secure random codes
• Audit Trail - Complete activation history logging

Device Monitoring

Real-Time Status

Administrators can monitor device status:

• Online/Offline Status - Real-time connectivity
• Last Activity - Timestamp of last employee interaction
• Current User - Employee currently using device (if any)
• Usage Statistics - Daily/weekly usage counts

Usage Analytics

Device Usage Metrics

• Total Punches - Lifetime clock-in/out count
• Daily Usage - Punches per day over time
• Peak Hours - Busiest usage times
• Employee Distribution - Which employees use which devices

Performance Monitoring

• Response Times - Clock-in/out processing speed
• Error Rates - Failed operations and causes
• Offline Periods - Duration and frequency of offline mode
• Sync Performance - Offline data sync success rates

Health Monitoring

Device Health Indicators

• Battery Level - For tablet/mobile devices
• Storage Space - Available local storage
• Camera Status - Camera functionality and quality
• Network Quality - Connection speed and stability

Alerts and Notifications

• Device Offline - Extended offline periods
• High Error Rates - Unusual failure patterns
• Storage Full - Local storage capacity issues
• Hardware Problems - Camera or sensor failures

API Endpoints

Device Management

List Devices

GET /api/devices?status=active&location=office

Query Parameters:

• status - Filter by device status
• location - Filter by location name
• limit - Results per page
• offset - Pagination offset

Response:

{
  "devices": [
    {
      "id": "device_id",
      "deviceId": "KIOSK_001",
      "deviceName": "Kiosk 1 - Head Office",
      "locationName": "Head Office",
      "locationAddress": "123 Collins Street, Melbourne",
      "status": "active",
      "lastActivity": "2024-01-15T14:30:00Z",
      "lastUsedBy": {
        "id": "employee_id",
        "name": "John Smith",
        "pin": "1001"
      },
      "totalPunches": 1250,
      "registeredAt": "2024-01-01T10:00:00Z"
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Register Device

POST /api/devices
Content-Type: application/json

{
  "deviceName": "Kiosk 2 - Warehouse",
  "locationName": "Warehouse",
  "locationAddress": "456 Industrial Drive, Melbourne"
}

Update Device

PATCH /api/devices/{deviceId}
Content-Type: application/json

{
  "deviceName": "Updated Kiosk Name",
  "status": "disabled"
}

Revoke Device

POST /api/devices/{deviceId}/revoke
Content-Type: application/json

{
  "reason": "Device compromised - security breach"
}

Device Activation

Activate Device

POST /api/device/activate
Content-Type: application/json

{
  "activationCode": "ABC123",
  "deviceFingerprint": {
    "userAgent": "Mozilla/5.0...",
    "screenResolution": "1920x1080",
    "timezone": "Australia/Melbourne"
  }
}

Check Activation Status

GET /api/device/status

Response:

{
  "isActivated": true,
  "deviceId": "KIOSK_001",
  "deviceName": "Kiosk 1 - Head Office",
  "locationName": "Head Office",
  "lastSync": "2024-01-15T14:30:00Z"
}

Clock Operations

Employee Clock Action

POST /api/device/clock
Content-Type: application/json

{
  "pin": "1001",
  "action": "in",
  "photo": "base64_image_data",
  "location": {
    "lat": -37.8136,
    "lng": 144.9631
  }
}

Device Hardware Recommendations

Tablet Devices

Recommended Specifications

• Screen Size - 10-13 inches for optimal visibility
• Resolution - 1920×1080 minimum for clear display
• RAM - 4GB minimum, 8GB recommended
• Storage - 64GB minimum for offline data
• Camera - Front-facing camera for face detection
• Connectivity - Wi-Fi and optional cellular backup

Recommended Models

• iPad (9th generation or later) - Excellent build quality and camera
• Samsung Galaxy Tab A8 - Good value Android option
• Microsoft Surface Go - Windows option with full browser support
• Amazon Fire HD 10 - Budget option with custom browser

Kiosk Hardware

Wall-Mounted Kiosks

• Enclosure - Secure, tamper-resistant housing
• Screen - 15-21 inch touchscreen display
• Computer - Mini PC or embedded system
• Camera - High-quality webcam for face detection
• Network - Ethernet preferred, Wi-Fi backup

Standalone Kiosks

• All-in-One Design - Integrated computer and display
• Height Adjustable - Accommodate different user heights
• Cable Management - Clean, professional appearance
• Security - Locked enclosure and cable protection

Network Requirements

Bandwidth

• Minimum - 1 Mbps for basic functionality
• Recommended - 5 Mbps for photo uploads
• Peak Usage - 10 Mbps during shift changes

Connectivity

• Primary - Ethernet connection preferred
• Backup - Wi-Fi or cellular for redundancy
• Offline Mode - Local storage for network outages
• Sync - Automatic sync when connection restored

Security Considerations

Physical Security

• Device Placement - Secure, monitored locations
• Cable Protection - Prevent tampering with connections
• Screen Protection - Tempered glass or protective film
• Enclosure Locks - Prevent unauthorised access

Network Security

• VPN Connection - Secure connection to company network
• Firewall Rules - Restrict access to required services only
• Certificate Pinning - Prevent man-in-the-middle attacks
• Regular Updates - Keep device software current

Data Security

• Local Encryption - Encrypt locally stored data
• Secure Transmission - HTTPS for all communications
• Data Minimisation - Store only necessary data locally
• Automatic Cleanup - Regular cleanup of old data

Access Control

• Device Authentication - Unique device certificates
• User Authentication - PIN-based employee access
• Admin Access - Separate admin authentication
• Audit Logging - Complete access and usage logs

Troubleshooting

Common Issues

Device Won't Activate

• Check Activation Code - Verify code is correct and not expired
• Network Connectivity - Ensure device has internet access
• Browser Compatibility - Use supported browser (Chrome, Safari, Edge)
• Clear Cache - Clear browser cache and cookies

Clock-In Not Working

• Device Status - Verify device is active and not disabled
• Employee PIN - Check PIN is correct and employee is active
• Camera Issues - Verify camera permissions and functionality
• Network Issues - Check internet connectivity

Offline Mode Problems

• Local Storage - Check available storage space
• Sync Queue - Monitor offline data sync status
• Network Recovery - Verify automatic sync when online
• Data Conflicts - Resolve duplicate or conflicting entries

Performance Issues

• Device Resources - Check RAM and CPU usage
• Network Speed - Test internet connection speed
• Cache Size - Clear browser cache if excessive
• Background Apps - Close unnecessary applications

Diagnostic Tools

Device Health Check

GET /api/device/health

Response:

{
  "status": "healthy",
  "checks": {
    "network": "connected",
    "camera": "functional", 
    "storage": "85% available",
    "lastSync": "2024-01-15T14:30:00Z"
  },
  "recommendations": [
    "Clear cache to free storage space"
  ]
}

Connection Test

GET /api/device/test-connection

Sync Status

GET /api/device/sync-status

Best Practices

Device Deployment

• Pilot Testing - Test with small group before full deployment
• User Training - Train employees on device usage
• Location Planning - Choose optimal device placement
• Backup Devices - Have spare devices for replacements

Maintenance

• Regular Cleaning - Keep screens and cameras clean
• Software Updates - Keep browser and OS updated
• Hardware Checks - Regular inspection of cables and mounts
• Performance Monitoring - Monitor device performance metrics

Security

• Regular Audits - Review device access logs
• Code Rotation - Generate new activation codes regularly
• Access Reviews - Review and revoke unused devices
• Incident Response - Have plan for security incidents

User Experience

• Clear Instructions - Provide simple usage instructions
• Visual Feedback - Ensure clear success/error indicators
• Help Information - Display contact information for assistance
• Accessibility - Consider accessibility requirements

Next Steps

• Device Registration - Detailed device registration process
• Kiosk Mode - Kiosk interface configuration and usage
• Activation Process - Step-by-step activation guide