Note: This is the guide for Ayva.js—the software library. It assumes basic familiarity with Open Source Multi Axis Stroker Robots, TCode, and JavaScript. If you are looking for the guide for the web application Ayva Stroker Lite, click here.

What is Ayva.js?

Ayva.js is a lightweight, behavior-based JavaScript library for controlling Open Source Multi Axis Stroker Robots such as the OSR2+, SR6, or any device that can be controlled with TCode. It allows specifying simple or complex multi-axis movements using an expressive Motion API. More complex behaviors can be constructed using a Behavior API.

Sponsor this project

patreon.com/soritesparadox

Quick Start

Web

To get started with Ayva.js for the web, simply copy the following code into an HTML file and open it in your browser:

<script src="https://unpkg.com/osr-emu/dist/osr-emu.dist.min.js"></script>
<script src="https://unpkg.com/ayvajs/dist/ayva.dist.min.js"></script>

<div id="emulator" style="height: 100vh"></div>

<script>
  const emulator = new OSREmulator('#emulator');
  const ayva = new Ayva().defaultConfiguration();
  ayva.addOutput(emulator);

  ayva.move({ to: 0, duration: 2 });
</script>

The above example imports the minified distributions of Ayva.js and the OSR Emulator from unpkg. It loads the emulator into an html element, creates a new instance of Ayva, adds the emulator as an output, and then commands the emulator to move to the bottom position over two seconds.

To connect to an actual device using the Web Serial API, you may use a WebSerialDevice. The following example creates a button that requests a connection to a device when clicked (we need to do this because the Web Serial API only allows a request to connect if it was triggered by a user gesture):

<script src="https://unpkg.com/ayvajs/dist/ayva.dist.min.js"></script>

<button id="connect" onclick="connect()">Connect</button>

<script>
  const ayva = new Ayva().defaultConfiguration();
  const device = new WebSerialDevice();

  function connect () {
    device.requestConnection().then(() => {
      ayva.addOutput(device);

      ayva.move({ to: 0, duration: 2 });
    }).catch((error) => {
      console.error('Error connecting to device:', error);
    });
  }
</script>

ES6 Module

Ayva.js (as well as the OSR Emulator) may also be imported as an ES6 module. Here are the previous examples rewritten using modules:

Emulator:

<div id="emulator" style="height: 100vh"></div>

<script type="module">
  import { Ayva } from 'https://unpkg.com/ayvajs';
  import { OSREmulator } from 'https://unpkg.com/osr-emu';

  const emulator = new OSREmulator('#emulator');
  const ayva = new Ayva().defaultConfiguration();
  ayva.addOutput(emulator);

  ayva.move({ to: 0, duration: 2 });
</script>

Actual Device:

<button id="connect" onclick="connect()">Connect</button>

<script type="module">
  import { Ayva, WebSerialDevice } from 'https://unpkg.com/ayvajs';
  const ayva = new Ayva().defaultConfiguration();
  const device = new WebSerialDevice();

  window.connect = function () {
    device.requestConnection().then(() => {
      ayva.addOutput(device);

      ayva.move({ to: 0, duration: 2 });
    }).catch((error) => {
      console.error('Error connecting to device:', error);
    });
  }
</script>

npm

Ayva.js can be installed and used in a Node.js app via npm:

npm install ayvajs

To import Ayva into your Node.js app:

import { Ayva } from 'ayvajs';

const ayva = new Ayva().defaultConfiguration();

// ...

Ayva.js does not provide any device implementations that work in a Node.js app. Instead, Ayva.js can work with an external library. The recommended serial library for Node.js is serialport:

npm install serialport

Then:

import { Ayva } from 'ayvajs';
import { SerialPort } from 'serialport';

// Create a new device on the specified port. 
// Note: /dev/cu.usbserial-0001 is just an example. Your port will likely be different.
const device = new SerialPort({ path: '/dev/cu.usbserial-0001', baudRate: 115200 });

const ayva = new Ayva().defaultConfiguration();
ayva.addOutput(device);

ayva.move({ to: 0, speed: 1 });

Note: This example is the syntax from version 10 of SerialPort.

When running in Node.js, your app will need to be configured with type module (in the package.json), or you will need to suffix your file with the .mjs extension and include that extension explicitly when running it. i.e.

node my-app.mjs

Versions

While Ayva.js is relatively stable, it is still considered to be under active development. It has not yet reached version 1.0.0. Therefore breaking changes might be introduced as the API matures. You can protect yourself from breaking changes by locking to a specific version.

Examples in this tutorial have all used the latest version. When importing using unpkg, to restrict to a specific version simply add @<version> into the url. Ex:

<script src="https://unpkg.com/ayvajs@0.14.0/dist/ayva.dist.min.js"></script>

ES6 module:

<script type="module">
  import { Ayva } from "https://unpkg.com/ayvajs@0.14.0";
</script>

Node.js app:

npm install ayvajs@0.14.0

All releases may be viewed here.