Technical Reference: Automatic Factory Reset & Device State Management

Overview

This document outlines the behavior of Raven devices when they are removed from an account but remain active in the field. It explains the relationship between physical hardware and cloud pairings (raven_uuid), and details the automatic factory reset logic designed to prevent data collisions and ensure smooth device redeployment.

Key Terminology

• Physical Unit: The actual hardware device identified by a Serial Number. 
• raven_uuid: A unique identifier representing a specific pairing between a Physical Unit and a Customer Account.
  • Note: A single physical unit may have multiple raven_uuids over its lifetime if it moves between accounts. This can be the case for rental models where devices change hands or if a device has been refurbished and redeployed to another account. 
  • The physical unit is given the raven_uuid at provisioning time, and will hold on to that value for the lifetime of the pairing.
• Device Shadow: The cloud-side configuration and settings file, which is keyed to the raven_uuid (not the physical serial number).
• RAVENLESS: A cloud database state indicating a raven_uuid has been removed from an account and is no longer valid.  It is not named particularly well.  A more appropriate name would be RAVEN_UNIT_LESS as the raven_uuid is still valid in the cloud, but there is no hardware attached to it any more.
• PROVISIONED: The standard active state where a device is successfully paired and communicating.

The Provisioning Lifecycle

To understand how the automatic reset functions, it is necessary to understand how the cloud identifies devices.

1. Assignment: When a physical unit is assigned to an account, the cloud generates a new raven_uuid.
2. Provisioning: The device receives this raven_uuid during setup. All subsequent communication (telemetry, video, settings) uses this ID.
3. Removal: When a user removes the device from the dashboard, the cloud marks that specific raven_uuid as RAVENLESS.  The device does not forget the raven_uuid until a factory reset is performed.

The "Stale State" Problem

A specific issue arises when a device is removed from an account in the cloud (marked RAVENLESS) but the physical device is not factory reset.  A factory reset can be performed remotely, but only if the physical device is online at the time.

• The physical device retains the old raven_uuid in its internal state.
• When the device eventually comes online (e.g., powered on by a new user), it attempts to upload data and retrieve settings using the old, invalid raven_uuid.
• Without intervention, the device remains paired to the old account locally, even though the cloud considers it removed.  Data from the device is discarded by the cloud because the device is in this state.

Automatic Factory Reset Logic

To resolve the "Stale State" problem without requiring manual intervention, the Raven cloud implements an Automatic Force Reset based on traffic analysis for a more efficient support and customer experience. 

Trigger Conditions

The system continually monitors incoming data streams. An automatic Factory Reset command is issued to the device only if all the following conditions are met:

1. Incoming Data from RAVENLESS Raven: The cloud receives data transmission from a device with a raven_uuid that is marked as RAVENLESS in the database.
2. Raven Unit ASSIGNED to a new account: There is another pairing for that physical unit to a new raven_uuid.

The Sequence of Events

1. Removal: A device is removed from an account via the API/Dashboard. The status changes to RAVENLESS.
2. Communication Attempt: The device (still holding the old configuration) connects to the internet and sends data.
3. Rejection & Command: The cloud recognizes the invalid raven_uuid and the new pairing and so it discards the incoming data and immediately responds with a Factory Reset command.
4. Device Wipe: Since the device is sending data, it is online, and should receive the Factory Reset command.  Once the command is received, the physical device will wipe its internal memory (including the old raven_uuid and stored video), and reboots.  The cloud will only send a Factory Reset command every 10 minutes to an individual device should the device not receive the command the first time.
5. Raven Check-in: The Raven that has been Factory Reset will enter into the Check-in mode which will request information from the cloud to provision.  Since there is a new ASSIGNED state for this Raven, it will provision on the new account, as described in more detail below.

Data Handling

• Data Security: Any data transmitted by a device in the RAVENLESS state is discarded immediately by the cloud.
• Local Storage: The Factory Reset will wipe all locally stored videos and settings on the device.

Device Behavior Post-Reset (The Checkmark Screen)

Once the automatic factory reset is complete, the device enters a "Waiting for Provisioning" state.

• Visual Indicator: The device screen will display a Checkmark.
• Connectivity: The device will periodically Check-in with the cloud to see if it has been assigned to a new account.
• Limitations: While on the Checkmark screen:
  • The device is not recording video.
  • The device is not reachable remotely via standard controls.
  • The device acts solely as a beacon waiting for assignment.
  • The device will continue to check-in until it has an assignment from the cloud.

Redeployment and Re-provisioning

If the physical unit is intended for a new customer, the workflow is seamless due to the raven_uuid architecture:

1. New Assignment: The physical unit is added to a new account in the database.
2. New Pairing: The cloud generates a new raven_uuid and sets the status to ASSIGNED.
3. Provisioning: The device (currently on the Checkmark screen) checks in. The cloud recognizes the physical serial number has a pending assignment.
4. Download: The device downloads the new raven_uuid.
5. Result: The device is now PROVISIONED on the new account. History and media are tracked under this new ID, completely separate from the previous installation.