Clarification Needed on Device Status Mapping for Integration with External Systems

[merih-sakarya]

I am currently working on integrating DeviceFarmer STF with our internal system and need to map the STF device statuses (status, present, ready, using etc.) to our system's device states (Initializing, ReadyToUse, InUse, Preparing, Offline). I require clarification or confirmation on the appropriate mappings to ensure accurate status reflections in our system.

Detailed Explanation of Each Device State:

• Offline: This state indicates that the device is either not physically connected or is experiencing operational issues (e.g., connection problems). Additionally, this state applies when attempts to prepare the device for use have failed due to internal errors or other issues preventing the device from becoming ready.
• Initializing: This state is assigned when a device is first detected by our system. It represents the initial processing stage where the system recognizes and begins to set up the device.
• Preparing: This state occurs as we attempt to make the device ready for use. Typically, this involves processes undertaken after each user session to reset or reconfigure the device. If the preparations are successful, the device transitions to the "ReadyToUse" state.
• ReadyToUse: In this state, the device is fully prepared and available for a user to select and use. It signifies that the device is functioning correctly and is awaiting user engagement.
• InUse: This state indicates that the device is currently being used. It reflects active engagement with the device by a user.

Proposed Device Status Mapping
Based on the STF documentation and the Device object parameters, I propose the following mappings:

• Offline: Mapped when status is not OK (status codes like UNAUTHORIZED, UNAVAILABLE, etc.), or present is false. This indicates that the device is either not connected or is experiencing operational issues that prevent it from being ready for use.
• Initializing: Mapped when status is OK, present is true, but both ready and using are false. This suggests that the device has been detected and is setting up but is not yet ready for use.
• Preparing: Mapped when status is OK, present is true, ready is false, and using is false, indicating the device is undergoing preparation for upcoming use.
• ReadyToUse: Mapped when status is OK, present and ready are true, and using is false. This indicates that the device is fully prepared and available for user interaction without being currently in use.
• InUse: Mapped when status is OK, and both present and using are true, which shows that the device is currently being actively used.

DeviceFarmer (STF) Device Status in wire.proto;

enum DeviceStatus {
  OFFLINE = 1;
  UNAUTHORIZED = 2;
  ONLINE = 3;
  CONNECTING = 4;
  AUTHORIZING = 5;
}

Java Method for Mapping DeviceFarmer (STF) Device Status to Internal Project Device State;

public DeviceState mapDeviceStatusToState(int status, boolean present, boolean ready, boolean using) {
    switch (status) {
        case 1:  // OFFLINE
            return DeviceState.Offline; // Device is disconnected or not functioning.
        
        case 2:  // UNAUTHORIZED
            return DeviceState.Offline; // Device cannot be used until authorized.
        
        case 3:  // ONLINE
            if (!present) {
                return DeviceState.Offline; // Device is marked online but not physically detected.
            } else if (!ready && !using) {
                return DeviceState.Initializing; // Device is present but not ready for use.
            } else if (ready && !using) {
                return DeviceState.ReadyToUse; // Device is ready but not currently in use.
            } else if (ready && using) {
                return DeviceState.InUse; // Device is actively being used.
            }
            break;
        
        case 4:  // CONNECTING
            return DeviceState.Preparing; // Device is in the process of setting up connection.
        
        case 5:  // AUTHORIZING
            return DeviceState.Initializing; // Device is undergoing authorization.
        
        default:
            return DeviceState.Offline; // Default fallback for any unknown status.
    }
    return DeviceState.Offline; // Default return if no conditions in ONLINE case match.
}

Questions

• Are the above mappings correct based on the standard usage and definitions within DeviceFarmer STF?
• Is there any additional documentation or examples on how these statuses are typically handled or should be interpreted in different contexts?

This integration is crucial for maintaining operational efficiency and accurate device management in our system. Any assistance or additional information you could provide would be greatly appreciated.

Thanks