Introduction

This manual provides a comprehensive guide to using the Cambrionix Device API, which enables users to control and manage devices connected to Cambrionix products. The API serves as a bridge between Cambrionix hubs and the devices they manage, offering a versatile programming interface for seamless control and data retrieval. The core functionality of the Cambrionix Device API resides within a locally installed service known as 'CambrionixDeviceAPI'.

This service enables developers and system administrators to automate device management tasks, such as querying device information, controlling device states, or executing commands, all through a standard and accessible HTTP-based interface. The API is particularly useful for scenarios involving multiple connected devices, where centralised control and monitoring are essential.

How the Cambrionix Device API Works

The Cambrionix Device API communicates via HTTP requests, allowing users to send commands and retrieve information over a network using widely supported protocols like HTTP and HTTPS. This makes the API platform-agnostic and compatible with a wide range of tools, including web browsers, command-line utilities, and custom applications.

To help facilitate these interactions, this manual will illustrate examples using cURL (Client URL), a powerful command-line tool used to automate HTTP requests and transfer data using various protocols such as HTTP, HTTPS, FTP, and more. Since cURL is widely used in scripting and automation, it's ideal for interacting with the Cambrionix Device API in scenarios where repetitive or automated device management tasks are necessary.

What is cURL?

cURL is a widely used command-line utility designed to send and receive data over a wide range of protocols, including HTTP and HTTPS. Its versatility makes it a popular tool for automating tasks in scripts, system management, and application development. In the context of the Cambrionix Device API, cURL allows users to send HTTP requests (e.g., GET, POST, PUT, DELETE) to the API and receive structured responses that can be processed for various purposes, such as monitoring device status or issuing commands.

Using cURL with the Cambrionix Device API

When interacting with the Cambrionix Device API, cURL plays a critical role in forming and sending the appropriate requests. These requests are composed of HTTP methods, such as:

Request Type Description
GET Retrieves information from a resource (e.g., querying device status or connected devices).
POST Sends data to the API to create or update resources (e.g., sending commands to connected devices).
DELETE Removes or disables specific resources (e.g., disconnecting a device or clearing settings).

Each request is sent to the API endpoint exposed by the 'CambrionixDeviceAPI' service, and the response is typically returned in a structured format like JSON or XML. These responses can then be parsed to obtain specific details about the devices being controlled, such as their current power status, charging progress, or connection status.

Automating Interactions with cURL

Since cURL can be integrated into shell scripts and other automation tools, it’s highly effective for automating routine tasks, such as checking the status of devices, turning devices on or off at specific times, or even managing firmware updates on connected devices. By incorporating cURL into your workflows, you can reduce manual interaction with the devices and create automated processes that respond to the changing needs of your device environment.

Prerequisites

Before using the Cambrionix Device API, several requirements must be fulfilled to ensure seamless operation. This section outlines the essential components, additional software, and system configurations needed to successfully interact with the API and connected devices. To begin using the Cambrionix Device API, you must ensure the following are in place:

  • Cambrionix Device API: Ensure that the Cambrionix Device API is installed and configured correctly on your system.

  • Firmware Version: The device must be running at least firmware version x.xx or higher for compatibility with the API.

  • Cambrionix Connect License: A valid Cambrionix Connect License is required for accessing and using the API’s full functionality.

Before proceeding with API usage, make sure that these components are installed, up-to-date, and properly licensed.

Additional software

Depending on the type of devices you are working with (iOS or Android), additional software may be required to facilitate communication between the Cambrionix hub and the connected devices.

  • iOS Devices

For iOS devices, the software requirements differ based on your operating system:

macOS: No additional software is required for macOS users, as the necessary components are built into the operating system. Commands for controlling iOS devices will work seamlessly with the inbuilt support provided by macOS.

Windows: For Windows users, Apple Mobile Device Support must be installed. This software comes bundled with iTunes. To communicate with iOS devices via the Cambrionix hub, you will need to download and install iTunes from the Microsoft store or from the following link https://www.apple.com/uk/itunes.

  • Android devices

For Android™ devices, communication is handled via Android Debug Bridge (ADB). This tool is included in the Android Platform Tools and allows interaction with Android devices through command-line instructions. You can download the ADB toolset from thehttps://developer.android.com/studio/command-line/adb.

Device trust

Certain commands and interactions may require the host system to be trusted by the connected device. This is particularly important when managing iOS or Android devices for the first time. When connecting a device to a new host for the first time, the device will prompt you with a dialogue box asking whether to Trust the host. You must select "Trust" to allow full communication and enable the API to perform its functions. Without this trust confirmation, some API commands may not work or may be restricted in their functionality.

Direct access to USB hardware

To ensure proper communication between the API and connected devices, the API must have direct access to the USB hardware. This requirement rules out the use of virtual machines (VMs) such as Parallels, VirtualBox, or Microsoft Hyper-V. Virtual environments often prevent the API from accurately detecting which USB device is connected to which physical port. Additionally, virtualisation can interfere with access to the serial devices needed for communication with the hub. As a result, the API may not be able to perform essential tasks like querying device information or issuing commands.

Sync capable charger for USB information

For the API to retrieve USB device information, there must be an active USB connection between the host machine and the connected device. This connection is only available on sync-capable products, which support both data transfer and charging, and will not work with charge-only ports.