Javascript

Import Package

Download the magic.js npm package by running the following command in your terminal.

npm i @indistinguishable-from-magic/magic-js

Include the package in your file by creating a reference to it.

const Magic = require('@indistinguishable-from-magic/magic-js');

If you are planning on using a USB connection, you will need to download the USB driver for your system and follow the install wizard. https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers?tab=downloads. We recommend this during development.

Connecting to Hardware

In order to pair directly to a piece of hardware, a user has to initialize the connection the first time they use your site. This user flow is a requirement set in place by underlying browser guardrails.

Note: Browser based serial connections are only supported by Chrome, Edge, and Opera. This means a hardware connection will not work when a website is opened on Safari or Firefox.

The easiest way for a user to initialize the connection is by providing a "connect button" for them to click.

// sample user flow to pair to hardware
function ConnectButton() { 
 
  function pair() {
    Magic.connect(); // ✨ only required code ✨
  }

  return (
    <button onClick={pair}>
      Connect to Hardware
    </button>
  );
}

A popup will appear for the user to choose the "serial port" and then click connect.

• For USB on a Mac, the port will be named "CP2102N USB to UART Bridge Controller (cu.SLAB_USBtoUART)."

• For Bluetooth on a Mac, the user will first pair over Bluetooth and then click: "cu.Device" in the popup window on the browser or "cu.{replace with unique name of their hardware}."

• For USB on Windows, the port will be named "CP2102N USB to UART Bridge Controller (COM#).

• For Bluetooth on Windows, the user will first pair over Bluetooth and then click: "Device" in the popup window on the browser or "{replace with unique name of their hardware}."

Disconnecting from Hardware

Disconnecting from the hardware can happen programmatically and does not have to be initialized by the user. You must disconnect before a user navigates away from a page or pairs again, otherwise there will be unexpected errors. When a page is reloaded it will automatically disconnect.

Magic.disconnect();

Streaming Data

You can access module data in multiple ways. The simplest way is to access the module and its property directly. For example, in the case of a Proximity Module, to access how close an object is you can use the following code.

var data = Magic.modules.proximity.amount;

If you have multiple of the same module plugged in, it will choose the module on the highest numbered port. To specify a module on a specific port you can pass the port number in your reference like so.

// get the slider's position on port 2
var data = Magic.modules.slider["2"].position;

To access the data of a specific port and not as a module you can reference the hardware.

// get the raw port data from port 3
var data = Magic.hardware["3"].data

All modules have a simplified mapped version of their data, to access the raw data stream of a module you can do so by referencing its raw property.

// get a slider's non-mapped raw position
var data = Magic.modules.slider.raw.position;

For all module properties you can visit a module's information page.