Activation Kit

Automated iOS device activation and supervision toolkit. This package uses pymobiledevice3 and USB device detection to automatically supervise iOS devices when connected.

Features

- 🔌 Automatic detection - Detects iOS devices when connected via USB
- 🔧 Automated supervision - Automatically supervises devices with your organization
- ⚡ Setup skipping - Configures devices to skip all setup assistant screens
- 🌍 Language/locale - Pre-configures language and locale settings
- 📡 Event-driven - Subscribe to activation events for monitoring

Prerequisites

1. Install pymobiledevice3:
``bash
pip install -U pymobiledevice3
`

2. Install iTunes (Windows only):
Download and install iTunes from Microsoft Store for USB device support.

3. Run as Administrator (Windows) or with sudo (macOS):
Some pymobiledevice3 commands require elevated privileges.

4. Configure WiFi credentials (for MDM enrollment):
Copy .env.example to .env and fill in your WiFi network credentials:
`bash
cp .env.example .env
# Edit .env with your WiFi SSID and password
`

Installation

`bash
npm install @mcesystems/activation-kit
`

Quick Start

`typescript
import { ActivationKit } from "@mcesystems/activation-kit";

// Create activation kit with your organization name
// This should match your enterprise certificate name
const activationKit = new ActivationKit({
organizationName: "Your Company Name",
language: "en",
locale: "en_US",
autoErase: true, // Erase device before supervision
});

// Listen for events
activationKit.onEvent((event) => {
switch (event.type) {
case "state_changed":
console.log([${event.udid}] State: ${event.previousState} → ${event.newState});
break;
case "activation_completed":
console.log(Device activated: ${event.udid});
break;
case "activation_failed":
console.log(Activation failed: ${event.error});
break;
}
});

// Activate multiple devices by UDID (each assigned logical port 1, 2, 3...)
await activationKit.activateAll([
"00008101-000C68290269001E",
"00008101-000123456789ABCD",
"00008101-000AABBCCDDEEFF0",
]);

// Or activate a single device
await activationKit.activate("00008101-000C68290269001E");

// Get device states
const allStates = activationKit.getAllDeviceStates();
const singleState = activationKit.getDeviceState("00008101-000C68290269001E");
`

Configuration

`typescript
interface ActivationConfig {
// Organization name for supervision (must match your certificate)
organizationName: string;

// Language code (default: "en")
language?: string;

// Locale code (default: "en_US")
locale?: string;

// Timeout for device reboot in ms (default: 120000)
rebootTimeout?: number;

// Timeout for each command in ms (default: 30000)
commandTimeout?: number;

// Auto-erase device before supervision (default: true)
autoErase?: boolean;

// Path to Python executable (default: "python")
pythonPath?: string;
}
`

Events

The onEvent callback receives events during the activation process:

| Event Type | Description |
|------------|-------------|
| device_connected | iOS device connected via USB |
| device_disconnected | iOS device disconnected |
| state_changed | Device activation state changed |
| activation_started | Activation process started |
| activation_completed | Device successfully activated |
| activation_failed | Activation process failed |
| command_output | Output from pymobiledevice3 command |

Device States

| State | Description |
|-------|-------------|
| disconnected | Device not connected |
| connected | Device connected, ready for activation |
| erasing | Device is being erased |
| waiting_for_reboot | Waiting for device to reboot |
| supervising | Applying supervision configuration |
| configuring | Setting language/locale |
| ready | Device is activated and ready |
| error | Activation failed |

Environment Variables

The example script (src/examples/activate-device.ts) supports loading configuration from a .env file. Create a .env file in the package directory (copy from .env.example) with your settings:

$3

`bash


Required: WiFi network name

WIFI_SSID=YourNetworkName

Required: WiFi password

WIFI_PASSWORD=YourPassword

Optional WiFi settings

WIFI_ENCRYPTION=WPA2 # WPA2, WPA3, WEP, None
WIFI_HIDDEN=false # true for hidden networks
WIFI_ENTERPRISE=false # true for 802.1X enterprise
WIFI_USERNAME= # Username for enterprise auth
WIFI_EAP_TYPE=PEAP # EAP type for enterprise

Alternative: Use existing profile file

WIFI_PROFILE_PATH=C:\path\to\WifiN.mobileconfig
`

$3

`bash
MDM_ENDPOINT=https://api-v5.mce-sys.com/mdm/graphql
MDM_AUTH_TOKEN=your-token-here # Auto-fetched if not provided
MDM_CERT_BASE64=base64-cert # Enterprise certificate for auto-trust
MDM_APP_ID=com.example.app # App bundle ID to install
MDM_APP_URL=https://example.com/app.ipa
`

Note: The .env file is gitignored and will not be committed to version control.

Scripts

$3

For testing with a local IPA file, use the create-local-manifest.ts script to generate a manifest.plist:

`bash


Basic usage

npx tsx scripts/create-local-manifest.ts path/to/app.ipa

With custom host and port

npx tsx scripts/create-local-manifest.ts path/to/app.ipa --host 192.168.1.100 --port 8000

With bundle ID and version

npx tsx scripts/create-local-manifest.ts path/to/app.ipa --bundle-id com.example.app --version 2.0.0
`

This will:
1. Create a manifest.plist file in the same directory as your IPA
2. Generate URLs pointing to your local HTTP server
3. Provide instructions for starting a local server

Example workflow:
`bash


1. Create manifest

npx tsx scripts/create-local-manifest.ts app.ipa --host 192.168.1.100 --port 8000

2. Start HTTP server in the IPA directory

cd /path/to/ipa/directory
python -m http.server 8000

3. Use the manifest URL in Postman or .env file

MDM_APP_URL=http://192.168.1.100:8000/app-manifest.plist

`

Options:
- --host - Local IP address or hostname (default: localhost)
- --port - HTTP server port (default: 8000)
- --bundle-id - Bundle identifier (default: auto-generated from filename)
- --version - Bundle version (default: 1.0.0)
- --title - App title (default: filename)
- --output - Output manifest file path (default: same dir as IPA)

Activation Flow

When a device is connected, the following steps are performed:

1. Check current state - Verify if device is already supervised with correct organization
2. Erase device (if autoErase: true) - Wipe the device to clear existing configuration
3. Wait for reboot - Wait for device to restart after erase
4. Supervise device - Apply supervision with organization name and skip-setup configuration
5. Install WiFi profile (if configured) - Install WiFi configuration for internet connectivity
6. Configure settings - Set language and locale
7. Pair device - Establish trust with the computer
8. Activate - Perform iCloud activation
9. MDM Enrollment (if configured) - Enroll device in MDM, install profiles and apps
10. Restart - Restart device to apply all settings

Direct pymobiledevice3 Access

You can also use the pymobiledevice3 wrapper functions directly:

`typescript
import {
listDevices,
eraseDevice,
superviseDevice,
setLanguage,
setLocale,
restartDevice,
getCloudConfiguration,
} from "@mcesystems/activation-kit";

// List connected devices
const devices = await listDevices();
console.log(devices);

// Erase a device
await eraseDevice("00008101-000C68290269001E");

// Supervise a device
await superviseDevice("00008101-000C68290269001E", "Your Org Name");

// Set language and locale
await setLanguage("00008101-000C68290269001E", "en");
await setLocale("00008101-000C68290269001E", "en_US");

// Restart device
await restartDevice("00008101-000C68290269001E");

// Check cloud configuration
const config = await getCloudConfiguration("00008101-000C68290269001E");
console.log(config?.IsSupervised);
`

Troubleshooting

$3

The organization name in the configuration must exactly match your enterprise certificate name. Check the certificate name in Keychain (macOS) or the app signing details.

$3

- Ensure the device is properly connected
- Try increasing rebootTimeout
- Check USB cable and port

$3

- Run as Administrator (Windows) or with sudo (macOS)
- Ensure the device has no existing cloud configuration, or use autoErase: true

$3

- Install it: pip install -U pymobiledevice3
- Verify Python is in PATH
- Try setting explicit pythonPath` in configuration

License

MIT