### Install the package

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/react-native-mcu-manager/README.md

Add the library to your project dependencies using npm.

```bash
npm install @playerdata/react-native-mcu-manager
```

--------------------------------

### Install npm dependencies

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install React Native MCU Manager

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Commands to install the package and configure native dependencies.

```bash
# Using pnpm
pnpm install @playerdata/react-native-mcu-manager

# Using npm
npm install @playerdata/react-native-mcu-manager

# For iOS, install pods
npx pod-install
```

--------------------------------

### Upgrade Class Usage

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Demonstrates how to use the `Upgrade` class to manage firmware update operations, including progress and state callbacks, starting, canceling, and destroying the upgrade process.

```APIDOC
## Upgrade Class Usage

### Description
This section details the usage of the `Upgrade` class for managing firmware update operations. It includes initialization with necessary options, handling progress and state changes, initiating the upgrade, canceling an ongoing process, and proper cleanup.

### Class
`Upgrade`

### Constructor Parameters
- **bleId** (string) - Required - The Bluetooth Low Energy device identifier (MAC address on Android, UUID on iOS).
- **updateFileUri** (string) - Required - The URI to the firmware update file.
- **options** (UpgradeOptions) - Required - Configuration options for the upgrade process.
  - **estimatedSwapTime** (number) - Required - Estimated time in seconds for the device to swap to the updated image.
  - **upgradeFileType** (UpgradeFileType) - Required - The type of the firmware file (e.g., `UpgradeFileType.BIN`, `UpgradeFileType.ZIP`).
  - **upgradeMode** (UpgradeMode) - Optional - The firmware upgrade strategy (defaults to `UpgradeMode.TEST_AND_CONFIRM`).
  - **eraseAppSettings** (boolean) - Optional - Whether to erase application settings during the upgrade.
  - **mcubootBufferCount** (number) - Optional - The number of concurrent packets for faster uploads.
- **onProgress** (function) - Optional - A callback function that receives the upload progress percentage (0-100).
- **onStateChange** (function) - Optional - A callback function that receives the current firmware upgrade state.

### Methods
- **runUpgrade()**: Initiates the firmware upgrade process. Returns a Promise that resolves on success or rejects on failure.
- **cancel()**: Cancels an in-progress firmware upgrade.
- **destroy()**: Releases native resources associated with the upgrade instance. This should always be called when the instance is no longer needed.

### Request Example
```typescript
import {
  Upgrade,
  UpgradeMode,
  UpgradeFileType,
  type FirmwareUpgradeState,
  type UpgradeOptions,
} from '@playerdata/react-native-mcu-manager';

const options: UpgradeOptions = {
  estimatedSwapTime: 60,
  upgradeFileType: UpgradeFileType.BIN,
  upgradeMode: UpgradeMode.TEST_AND_CONFIRM,
  eraseAppSettings: false,
  mcubootBufferCount: 3,
};

const onProgress = (progress: number) => {
  console.log(`Upload progress: ${progress}%`);
};

const onStateChange = (state: FirmwareUpgradeState) => {
  console.log(`Upgrade state: ${state}`);
};

const upgrade = new Upgrade(
  'AA:BB:CC:DD:EE:FF', // bleId
  'file:///path/to/firmware.bin', // updateFileUri
  options,
  onProgress,
  onStateChange
);

try {
  await upgrade.runUpgrade();
  console.log('Upgrade completed successfully');
} catch (error) {
  console.error('Upgrade failed:', error.message);
}

// To cancel:
// upgrade.cancel();

// IMPORTANT: Always destroy to release native resources
// upgrade.destroy();
```

### Response Example
(No direct response body for `runUpgrade`, success is indicated by promise resolution and completion logs, failure by promise rejection and error logs.)
```

--------------------------------

### Install react-native-mcu-manager with pnpm

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Add the package to your project dependencies using pnpm.

```bash
pnpm install @playerdata/react-native-mcu-manager
```

--------------------------------

### Get Bootloader Information

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Retrieves bootloader configuration and capabilities for a connected device. Requires the device's BLE ID. Logs details like bootloader name, buffer count and size, downgrade protection status, and operational mode.

```typescript
import {
  bootloaderInfo,
  type BootloaderInfo,
  MCUBootMode,
} from '@playerdata/react-native-mcu-manager';

try {
  // bleId: MAC address on Android, UUID on iOS
  const info: BootloaderInfo = await bootloaderInfo('AA:BB:CC:DD:EE:FF');

  console.log('Bootloader:', info.bootloader); // e.g., "MCUboot" or null
  console.log('Buffer Count:', info.bufferCount); // Number of buffers available
  console.log('Buffer Size:', info.bufferSize); // Size of each buffer in bytes
  console.log('No Downgrade:', info.noDowngrade); // true if downgrades are blocked
  console.log('Mode:', info.mode); // MCUBootMode value

  // Check MCUboot mode
  if (info.mode === MCUBootMode.MCUBOOT_MODE_SWAP_USING_SCRATCH) {
    console.log('Device uses swap with scratch partition');
  }
} catch (error) {
  console.error('Failed to get bootloader info:', error.message);
}
```

--------------------------------

### React Hook for Firmware Updates

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

A custom React hook to manage firmware updates, including state tracking for progress and status, and functions to start or cancel the update process. It handles initialization, cleanup, and error reporting.

```typescript
import {
  Upgrade,
  UpgradeMode,
  UpgradeFileType,
  type FirmwareUpgradeState,
} from '@playerdata/react-native-mcu-manager';
import { useState, useEffect, useRef } from 'react';

const useFirmwareUpdate = (
  bleId: string | null,
  updateFileUri: string | null,
  upgradeFileType: UpgradeFileType,
  upgradeMode?: UpgradeMode
) => {
  const [progress, setProgress] = useState(0);
  const [state, setState] = useState<FirmwareUpgradeState | string>('');
  const upgradeRef = useRef<Upgrade | null>(null);

  useEffect(() => {
    if (!bleId || !updateFileUri) {
      return () => null;
    }

    const upgrade = new Upgrade(
      bleId,
      updateFileUri,
      {
        estimatedSwapTime: 60,
        upgradeMode,
        upgradeFileType,
      },
      setProgress,
      setState
    );

    upgradeRef.current = upgrade;

    // Cleanup on unmount or dependency change
    return function cleanup() {
      upgrade.cancel();
      upgrade.destroy();
    };
  }, [bleId, upgradeFileType, updateFileUri, upgradeMode]);

  const runUpdate = async (): Promise<void> => {
    try {
      if (!upgradeRef.current) {
        throw new Error('No upgrade instance - missing bleId or updateFileUri');
      }
      await upgradeRef.current.runUpgrade();
    } catch (ex: unknown) {
      const errorMessage = ex instanceof Error ? ex.message : 'Unknown error';
      setState(errorMessage);
    }
  };

  const cancelUpdate = (): void => {
    upgradeRef.current?.cancel();
  };

  return { progress, runUpdate, state, cancelUpdate };
};

// Usage in a component
const FirmwareUpdateScreen = () => {
  const { progress, runUpdate, state, cancelUpdate } = useFirmwareUpdate(
    'AA:BB:CC:DD:EE:FF',
    'file:///path/to/firmware.bin',
    UpgradeFileType.BIN,
    UpgradeMode.TEST_AND_CONFIRM
  );

  return (
    <View>
      <Text>State: {state}</Text>
      <Text>Progress: {progress}%</Text>
      <Button onPress={runUpdate} title="Start Update" />
      <Button onPress={cancelUpdate} title="Cancel" />
    </View>
  );
};

```

--------------------------------

### Prebuild Expo project

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Prebuild the Expo project for development.

```bash
cd example

npx expo prebuild
```

--------------------------------

### Open project in IDE

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Open the iOS or Android IDE from the top level of the repository.

```bash
npm run open:(ios|android)
```

--------------------------------

### Run unit tests

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Execute unit tests for the project.

```bash
pnpm run typecheck run test
```

--------------------------------

### bootloaderInfo

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Retrieves information about the device's bootloader configuration and capabilities.

```APIDOC
## bootloaderInfo Function

### Description
Retrieves information about the device's bootloader configuration and capabilities.

### Method
`POST` (Assumed, as it's a function call that likely interacts with native code)

### Endpoint
`/playerdata/react-native-mcu-manager/bootloaderInfo`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bleId** (string) - Required - MAC address on Android, UUID on iOS.

### Request Example
```json
{
  "bleId": "AA:BB:CC:DD:EE:FF"
}
```

### Response
#### Success Response (200)
- **bootloader** (string | null) - The name of the bootloader, e.g., "MCUboot" or null.
- **bufferCount** (number) - The number of buffers available.
- **bufferSize** (number) - The size of each buffer in bytes.
- **noDowngrade** (boolean) - True if downgrades are blocked, false otherwise.
- **mode** (MCUBootMode) - The current operational mode of the bootloader.

#### Response Example
```json
{
  "bootloader": "MCUboot",
  "bufferCount": 4,
  "bufferSize": 1024,
  "noDowngrade": false,
  "mode": 1 
}
```

### MCUBootMode Enum
- **MCUBOOT_MODE_SINGLE_SLOT** (0) - Single slot, no fallback
- **MCUBOOT_MODE_SWAP_USING_SCRATCH** (1) - Swap with scratch partition
- **MCUBOOT_MODE_UPGRADE_ONLY** (2) - Upgrade only, no swap
- **MCUBOOT_MODE_SWAP_USING_MOVE** (3) - Swap using move operations
- **MCUBOOT_MODE_DIRECT_XIP** (4) - Direct execute in place
- **MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT** (5) - XIP with revert capability
- **MCUBOOT_MODE_RAM_LOAD** (6) - Load to RAM
- **MCUBOOT_MODE_FIRMWARE_LOADER** (7) - Firmware loader mode
```

--------------------------------

### Run typecheck and lint

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Verify code quality by running TypeScript and ESLint checks.

```bash
pnpm run typecheck
pnpm run lint
```

--------------------------------

### Manage Firmware Upgrades with Upgrade Class

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Implementation of the Upgrade class to handle firmware update lifecycles, including progress tracking and state management.

```typescript
import {
  Upgrade,
  UpgradeMode,
  UpgradeFileType,
  type FirmwareUpgradeState,
  type UpgradeOptions,
} from '@playerdata/react-native-mcu-manager';

// Create upgrade options
const options: UpgradeOptions = {
  // Required: estimated time for device to swap to updated image (seconds)
  estimatedSwapTime: 60,
  // Required: type of firmware file
  upgradeFileType: UpgradeFileType.BIN, // or UpgradeFileType.ZIP for manifest-based updates
  // Optional: upgrade mode (defaults to TEST_AND_CONFIRM)
  upgradeMode: UpgradeMode.TEST_AND_CONFIRM,
  // Optional: erase app settings during upgrade
  eraseAppSettings: false,
  // Optional: concurrent packet count for faster uploads
  mcubootBufferCount: 3,
};

// Progress callback (0-100)
const onProgress = (progress: number) => {
  console.log(`Upload progress: ${progress}%`);
};

// State change callback
const onStateChange = (state: FirmwareUpgradeState) => {
  // States: 'NONE' | 'VALIDATE' | 'UPLOAD' | 'TEST' | 'RESET' | 'CONFIRM' | 'SUCCESS' | 'UNKNOWN'
  console.log(`Upgrade state: ${state}`);
};

// Create upgrade instance
// bleId: MAC address on Android, UUID on iOS
const upgrade = new Upgrade(
  'AA:BB:CC:DD:EE:FF', // bleId
  'file:///path/to/firmware.bin', // updateFileUri
  options,
  onProgress,
  onStateChange
);

// Start the upgrade process
try {
  await upgrade.runUpgrade();
  console.log('Upgrade completed successfully');
} catch (error) {
  console.error('Upgrade failed:', error.message);
}

// Cancel an in-progress upgrade
upgrade.cancel();

// IMPORTANT: Always destroy to release native resources
upgrade.destroy();
```

--------------------------------

### useFirmwareUpdate Hook

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

A React hook for managing firmware updates, including state tracking and cleanup.

```APIDOC
## useFirmwareUpdate Hook

### Description
Provides a React hook to manage the firmware update process, including progress tracking, state management, and cancellation.

### Parameters
- **bleId** (string | null) - Required - The Bluetooth identifier (MAC address or UUID) of the device.
- **updateFileUri** (string | null) - Required - The URI of the firmware update file.
- **upgradeFileType** (UpgradeFileType) - Required - The type of the firmware file (e.g., BIN, ZIP).
- **upgradeMode** (UpgradeMode) - Optional - The mode for the upgrade process.

### UpgradeFileType Enum
- **BIN**
- **ZIP**

### UpgradeMode Enum
- **TEST_AND_CONFIRM**
- **DIRECT**
- **TEST_ONLY**

### Return Values
- **progress** (number) - The current progress of the firmware update (0-100).
- **runUpdate** (function) - A function to start the firmware update process.
- **state** (FirmwareUpgradeState | string) - The current state of the firmware update process or an error message.
- **cancelUpdate** (function) - A function to cancel the ongoing firmware update.

### Example Usage
```javascript
import { useFirmwareUpdate, UpgradeFileType, UpgradeMode } from '@playerdata/react-native-mcu-manager';

const FirmwareUpdateComponent = () => {
  const { progress, runUpdate, state, cancelUpdate } = useFirmwareUpdate(
    'AA:BB:CC:DD:EE:FF',
    'file:///path/to/firmware.bin',
    UpgradeFileType.BIN,
    UpgradeMode.TEST_AND_CONFIRM
  );

  return (
    <View>
      <Text>State: {state}</Text>
      <Text>Progress: {progress}%</Text>
      <Button onPress={runUpdate} title="Start Update" />
      <Button onPress={cancelUpdate} title="Cancel" />
    </View>
  );
};
```
```

--------------------------------

### Define Upgrade Strategies with UpgradeMode

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Available firmware upgrade strategies ranging from safe recovery modes to direct upload modes.

```typescript
import { UpgradeMode } from '@playerdata/react-native-mcu-manager';

// TEST_AND_CONFIRM (Recommended) - Process: upload, test, reset, confirm
// Can recover from bad firmware by reverting on failed boot
const safeMode = UpgradeMode.TEST_AND_CONFIRM; // value: 1

// CONFIRM_ONLY - Process: upload, confirm, reset
// WARNING: Cannot recover if device fails to boot new image
const riskyMode = UpgradeMode.CONFIRM_ONLY; // value: 2

// TEST_ONLY - Process: upload, test, reset
// Useful for running tests before manually confirming
const testMode = UpgradeMode.TEST_ONLY; // value: 3

// UPLOAD_ONLY - Process: upload, reset
// Immediately resets after upload, runs new image on next boot
const uploadMode = UpgradeMode.UPLOAD_ONLY; // value: 4
```

--------------------------------

### Specify Firmware File Format with UpgradeFileType

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Enum values for defining the firmware update file structure.

```typescript
import { UpgradeFileType } from '@playerdata/react-native-mcu-manager';

// Single binary update image
const binFile = UpgradeFileType.BIN; // value: 0

// Zip file with manifest.json describing contents
const zipFile = UpgradeFileType.ZIP; // value: 1
```

--------------------------------

### Configure Expo permissions

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/react-native-mcu-manager/README.md

Define Android permissions and iOS usage descriptions in your Expo configuration file.

```json
{
  "expo": {
    "android": {
      "permissions": [
        "ACCESS_FINE_LOCATION",
        "ACCESS_COARSE_LOCATION",
        "BLUETOOTH_SCAN",
        "BLUETOOTH_CONNECT"
      ]
    },
    "ios": {
      "infoPlist": {
        "NSBluetoothAlwaysUsageDescription": "Requires Bluetooth to perform firmware updates."
      }
    }
  }
}
```

--------------------------------

### UpgradeMode Enum

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Defines the different firmware upgrade strategies available with the `Upgrade` class.

```APIDOC
## UpgradeMode Enum

### Description
The `UpgradeMode` enum specifies the firmware upgrade strategy to be used. Each mode offers different levels of safety and process steps.

### Enum Values
- **TEST_AND_CONFIRM** (1): Recommended mode. Process: upload, test, reset, confirm. Allows recovery from bad firmware by reverting on failed boot.
- **CONFIRM_ONLY** (2): Process: upload, confirm, reset. Warning: Cannot recover if the device fails to boot the new image.
- **TEST_ONLY** (3): Process: upload, test, reset. Useful for running tests before manual confirmation.
- **UPLOAD_ONLY** (4): Process: upload, reset. Resets immediately after upload; the new image runs on the next boot.

### Usage Example
```typescript
import { UpgradeMode } from '@playerdata/react-native-mcu-manager';

const safeMode = UpgradeMode.TEST_AND_CONFIRM;
const riskyMode = UpgradeMode.CONFIRM_ONLY;
const testMode = UpgradeMode.TEST_ONLY;
const uploadMode = UpgradeMode.UPLOAD_ONLY;
```
```

--------------------------------

### UpgradeFileType Enum

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Specifies the format of the firmware update file used in the upgrade process.

```APIDOC
## UpgradeFileType Enum

### Description
The `UpgradeFileType` enum indicates the format of the firmware file being used for the update.

### Enum Values
- **BIN** (0): Represents a single binary update image.
- **ZIP** (1): Represents a zip file containing the firmware image and a manifest.json file.

### Usage Example
```typescript
import { UpgradeFileType } from '@playerdata/react-native-mcu-manager';

const binFile = UpgradeFileType.BIN;
const zipFile = UpgradeFileType.ZIP;
```
```

--------------------------------

### resetDevice

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Performs a soft reset on the connected device.

```APIDOC
## resetDevice Function

### Description
Performs a soft reset on the connected device.

### Method
`POST` (Assumed, as it's a function call that likely interacts with native code)

### Endpoint
`/playerdata/react-native-mcu-manager/resetDevice`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bleId** (string) - Required - MAC address on Android, UUID on iOS.

### Request Example
```json
{
  "bleId": "AA:BB:CC:DD:EE:FF"
}
```

### Response
#### Success Response (200)
Indicates that the device reset has been initiated.

#### Response Example
```json
{
  "message": "Device reset initiated"
}
```
```

--------------------------------

### Fix formatting errors

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Automatically fix formatting errors identified by TypeScript and ESLint.

```bash
pnpm run typecheck run lint --fix
```

--------------------------------

### MCUBootMode Enum Values

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Defines the various operational modes for the MCUboot bootloader. Each mode corresponds to a specific firmware update or management strategy.

```typescript
import { MCUBootMode } from '@playerdata/react-native-mcu-manager';

// Available MCUboot modes:
MCUBootMode.MCUBOOT_MODE_SINGLE_SLOT;           // 0 - Single slot, no fallback
MCUBootMode.MCUBOOT_MODE_SWAP_USING_SCRATCH;    // 1 - Swap with scratch partition
MCUBootMode.MCUBOOT_MODE_UPGRADE_ONLY;          // 2 - Upgrade only, no swap
MCUBootMode.MCUBOOT_MODE_SWAP_USING_MOVE;       // 3 - Swap using move operations
MCUBootMode.MCUBOOT_MODE_DIRECT_XIP;            // 4 - Direct execute in place
MCUBootMode.MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT; // 5 - XIP with revert capability
MCUBootMode.MCUBOOT_MODE_RAM_LOAD;              // 6 - Load to RAM
MCUBootMode.MCUBOOT_MODE_FIRMWARE_LOADER;       // 7 - Firmware loader mode
```

--------------------------------

### eraseImage

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Erases the secondary firmware image slot on the device.

```APIDOC
## eraseImage Function

### Description
Erases the secondary firmware image slot on the device.

### Method
`POST` (Assumed, as it's a function call that likely interacts with native code)

### Endpoint
`/playerdata/react-native-mcu-manager/eraseImage`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bleId** (string) - Required - MAC address on Android, UUID on iOS.

### Request Example
```json
{
  "bleId": "AA:BB:CC:DD:EE:FF"
}
```

### Response
#### Success Response (200)
Indicates successful erasure of the image.

#### Response Example
```json
{
  "message": "Image erased successfully"
}
```
```

--------------------------------

### Reset Connected Device

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Initiates a soft reset on the connected device. Requires the device's BLE ID. Logs confirmation or error messages.

```typescript
import { resetDevice } from '@playerdata/react-native-mcu-manager';

try {
  // bleId: MAC address on Android, UUID on iOS
  await resetDevice('AA:BB:CC:DD:EE:FF');
  console.log('Device reset initiated');
} catch (error) {
  console.error('Failed to reset device:', error.message);
}
```

--------------------------------

### Update Device with McuManager

Source: https://github.com/playerdata/react-native-mcu-manager/blob/main/README.md

Use the McuManager.updateDevice function to update a device. Ensure the bluetoothId is a MAC address on Android and a UUID on iOS. The upgradeOptions object can specify estimatedSwapTime, and callbacks are provided for upload progress and state changes.

```typescript
import McuManager,
  UpgradeOptions,
} from '@playerdata/react-native-mcu-manager';

const upgradeOptions: UpgradeOptions = {
  estimatedSwapTime: 30,
};

const onUploadProgress = (progress: number) => {
  console.log('Upload progress: ', progress);
};

const onUploadStateChanged = (state: string) => {
  console.log('Upload state change: ', state);
};

// bluetoothId is a MAC address on Android, and a UUID on iOS
McuManager.updateDevice(
  bluetoothId,
  fileUri,
  upgradeOptions,
  onUploadProgress,
  onUploadStateChanged
);
```

--------------------------------

### Erase Secondary Firmware Image

Source: https://context7.com/playerdata/react-native-mcu-manager/llms.txt

Erases the secondary firmware image slot on the connected device. Requires the device's BLE ID. Logs success or error messages.

```typescript
import { eraseImage } from '@playerdata/react-native-mcu-manager';

try {
  // bleId: MAC address on Android, UUID on iOS
  await eraseImage('AA:BB:CC:DD:EE:FF');
  console.log('Image erased successfully');
} catch (error) {
  console.error('Failed to erase image:', error.message);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.