ayvajs

A lightweight, behavior-based JavaScript API for controlling Open Source Multi Axis Stroker Robots.

Usage no npm install needed!

<script type="module">
  import ayvajs from 'https://cdn.skypack.dev/ayvajs';
</script>

README

ayva

What is Ayva?

Ayva is a lightweight, behavior-based JavaScript library for controlling Open Source Multi Axis Stroker Robots.

The following codepen examples demo some of the capabilities of Ayva and show how trivial it is to setup and perform complex movements (as well as demonstrate the usage of the OSR Emulator—a useful component for visualizing and testing movements without an actual hardware device):

Orbit Grind
Classic Stroke
Custom Behavior
Random Stroker

Features:

  • Perform arbitrarily complex movements across multiple axes using an expressive Motion API.
  • Construct arbitrarily complex behaviors using an action queue based Behavior API.
  • Built-in common motion shapes (cosine, parabolic, linear, tempest).
  • Built-in Classic Stroke behavior and orbital motion based behavior (Tempest Stroke).
  • Run built-in patterns by name (orbit-grind, vortex-tease, swirl-tease, etc)
  • Configurable. Setup an arbitrary number of axes with limits, alias, and type (linear, rotation, or auxiliary).
  • Abstracts away low level details such as outputing TCode.
  • Supports outputing commands to multiple devices at once.
  • Agnostic about the nature of the target device(s) (doesn't care if device is simulated or actual).
  • Cross platform with zero dependencies.
  • Runs in a browser, as part of a Node.js app, or theoretically anywhere with a JavaScript runtime.
  • Extensively tested (100% coverage).
  • Thoroughly documented.
  • Quick and easy setup.

Quick Start

CDN

In a browser, Ayva can be imported as an ES6 module using a CDN such as unpkg:

<!DOCTYPE html>
<body>
  <script type="module">
    import Ayva from 'https://unpkg.com/ayvajs';

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

    // ...
  </script>
</body>

One or more output devices must be added to an instance of Ayva in order to do anything. You may create your own device object (any object with a write method is considered an output device), or you may use the simple Web Serial API based WebSerialDevice provided:

<!DOCTYPE html>
<body>
  <button id="connect">Connect</button>

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

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

    document.querySelector('#connect').addEventListener('click', () => {
      device.requestConnection().then(() => {
        ayva.addOutputDevice(device);

        // I can now start using Ayva to control the device.
        // Send a command to move the default axis to position zero at 1 unit per second.
        ayva.move({ to: 0, speed: 1 });
      }).catch((error) => {
        console.error('Error connecting to device:', error);
      });
    });
  </script>
</body>

Note: in the example above we needed to request a connection to the device after a button click. This is because the Web Serial API only allows a request to connect if it was triggered by a user gesture.

npm

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

npm install ayvajs

And imported like so:

import Ayva from 'ayvajs';

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

// ...

Ayva does not provide any device implementations that work in a Node.js app. Instead, Ayva 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';

const device = new SerialPort('/dev/cu.usbserial-0001');

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

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

Note: The port used above (/dev/cu.usbserial-0001) is just an example. Yours may be different.

Tutorials

For more detailed information on how to use Ayva, see the following tutorials provided in the Documentation:

Getting Started
Configuration
Motion API
Behavior API