libijs

A node.js library for communicating with iOS devices over USB.

This is a pure javascript implementation of libimobiledevice, implementing everything needed for communicating with iOS device services through usbmuxd (the dameon\service responsible for communication with iOS devices over USB). Our goal is to evantually provide most of libimobiledevice's functionality, in an API suitable for node.js.

Note that libijs is still an early proof of concept, and is not ready for production yet.

Features

• Provides a convenient node.js API for communicating with iOS devices and their services over usbmuxd.
• Provides base classes for implementing more services, like the PropertyListService class.
• Implements several ready to use command line tools.

Current status

• usbmux (client): All known functionality is implemented
• lockdownd:
  • Implemented commands:
    • QueryType
    • StartSession\StopSession
    • StartService
    • GetValue\SetValue\RemoveValue
  • Pairing, which is handled by usbmuxd, is not implemented (yet).
• Implemented Services:
  • afc:
    • Multiplexes requests over a single connection to the afc service. Combined with node's async nature, this introduces a major performance improvment over libimobiledevice's afc client.
    • Provides a convient native interface:
      • node.js stream interface for reading\writing remote files
      • Walking remote dirs
  • diagnostics_relay
  • installation_proxy
  • MCInstall
  • mobileactivationd
  • mobilebackup2
  • notification_proxy
  • springboardservices
  • syslog_relay
• Tools:
  • apps: similar to ideviceinstaller. Currently supports listing, installing (excluding ipcc) and uninstalling apps
  • backup: similar to libimobiledevice's idevicebackup2.c, currently supports only backup & restore operations
  • diagnostics: similar to libimobiledevice's idevicediagnostics
  • info: similar to libimobiledevice's ideviceinfo
  • syslog: similar to libimobiledevice's idevicesyslog

Installation

Simply install using npm\yarn:

npm install libijs

or

yarn add libijs

Implementation Details

• The deviceManager uses one permanent usbmuxd connection for device listing and monitoring. Thus, the deviceManager will always maintain an updated list of connected devices, reducing the overhead of querying usbmuxd each time a device list is needed.
• AFC implementation uses the "packet number" to track requests\responses, enabling it to send multiple requests simultaneously. For example, when downloading a remote folder, "download file" requests are sent while "walking" the remote folder, which seems to greatly improve performance.
• We use our own implementations for the usbmux client and binary plist handling.
• Instead of using Promises and EventEmitters, we use our internal JarvisEmitter.

Usage\API examples

TODO

Examples

• Connect to lockdownd and query a value:

  constlibijs=require("libijs");constmeaco=require("meaco");constudid= ...;constqueryDeviceVersion=functionqueryDevice(device){returnmeaco(function*doQueryDevice(){// Connect to lockdowndconstlockdownClient=yieldlibijs.lockdownd.getClient(device);// Query the device type and iOS versionconstproductType=yieldlockdownClient.getValue(null,"ProductType");constiosVersion=yieldlockdownClient.getValue(null,"ProductVersion");console.log(`${productType} device running iOS ${iosVersion}`);yieldlockdownClient.close();});};constdeviceManager=libijs.createClient().deviceManager;deviceManager.ready(()=>{constdevice=deviceManager.getDevice(udid);if(device){queryDeviceVersion(device);}else{console.log("Couldn't find device");}});

• Download a file using the AFC stream API:

  constlibijs=require("libijs");constmeaco=require("meaco");constJarvisEmitter=require("jarvis-emitter");constfs=require("fs");constudid= ...;constafcExample=functionafcExample(afcClient){returnmeaco(function*doAfcExample(){// List a remote diryieldafcClient.walk("/",false,true).item((item)=>{console.log(`${item.relativeToRoot} - ${item.stats.st_size} bytes`);});// Download a fileyieldafcClient.downloadFile("DCIM/100APPLE/IMG_0001.JPG","./IMG_0001.JPG");// Use the stream api to read a fileconsole.log("\nVoiceMemos.plist:");constremoteFile=yieldafcClient.openFileAsReadableStream("iTunes_Control/iTunes/VoiceMemos.plist");constfileReadDone=newJarvisEmitter();remoteFile.on("data",(data)=>{console.log(data.toString());}).on("end",()=>{fileReadDone.callDone();});yieldfileReadDone;// Disconnect from the afcd serviceyieldafcClient.close();});};constdeviceManager=libijs.createClient().deviceManager;deviceManager.ready(()=>{constdevice=deviceManager.getDevice();libijs.services.getService(device,"afc").done(afcExample);});

Legal

Refer to the LICENSE file for libijs licensing terms.
Apple, iTunes, iPhone, iPad, Apple Watch, iPod, and iPod Touch are trademarks of Apple Inc.