This tutorial assumes that you have completed the Getting Started tutorial, and that you have some familiarity with Open Source Multi Axis Stroker Robots, TCode, and JavaScript.

Default Configuration

To control a device with an instance of Ayva, the axes for the device must be configured. The default configuration consists of the axes needed to control an OSR2 or SR6 device:

Axis Type Alias
L0 linear stroke
L1 linear surge
L2 linear sway
R0 rotation twist
R1 rotation roll
R2 rotation pitch
A0 auxiliary valve
A1 auxiliary suck
A2 auxiliary lube
V0 auxiliary vibe0
V1 auxiliary vibe1

An instance of Ayva can use the default configuration by calling the defaultConfiguration() method:

const ayva = new Ayva();

This method also returns the Ayva instance itself, allowing the above code to be reduced to one line:

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

After axes have been configured (and an output has been added) Ayva can begin generating TCode:

// Move the twist axis to position zero over 1 second.
  axis: 'twist', // An axis can be referred to by its name or alias (i.e. 'R0' would also work here).
  to: 0,
  duration: 1

Note: The Motion API is explained in greater detail in the next tutorial.


Ayva can output to a function or any object with a write() method. This allows the flexibility to connect to any kind of output. The following example just logs the TCode generated to the console:

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


// The TCode generated by the following command would simply be output to the console.
  axis: 'L0',
  to: 1,
  speed: 2

When Ayva is being used within a web application, the convenience class WebSerialDevice may be used to connect to an actual device. For graphical simulation, there is the OSR Emulator. In a Node.js app, the serial library serialport may be used.

Axis Limits

Axis values in Ayva are specified in the range [0, 1]. Internally, when values are translated to TCode they are scaled to the range [0, 9999]. For example, the following would result in the L0 axis moving to position 9999:

  axis: 'L0',
  to: 1,
  duration: 1

An axis can be configured to scale values to a smaller range. For existing axes this can be done with the updateLimits() method:

ayva.updateLimits('pitch', 0.3, 0.7);

// The following would now result in the pitch axis moving to about position 7000.
  axis: 'pitch',
  to: 1,
  duration: 1

Custom Axis Configuration

An axis configuration consists of the following parameters:

Parameter Type Attributes Default Description
name String

the machine name of the axis (such as L0, R0, etc...)

type String

linear, rotation, or auxiliary

alias String <optional>

an alias used to refer to the axis (such as twist, pitch, stroke, etc)

max Number <optional>

specifies maximum value for the axis

min Number <optional>

specifies minimum value for the axis

defaultValue Number <optional>
0.5 for linear axes, 0 for auxiliary

specifies the default value for the axis

resetOnStop Boolean <optional>

setting this flag will send the axis to its default value when ayva.stop() is called.

The configureAxis() method can be used to configure a single axis:

  name: 'C0',
  type: 'linear',
  alias: 'custom',
  max: 0.9,
  min: 0.1,

  axis: 'C0',
  to: 0,
  speed: 1,

Alternatively a configuration object with multiple axes can be passed to Ayva's constructor.

// Create a new config that only consists of the stroke and roll axis (an OSR2 without any mods)
const config = {
  name: 'OSR2',      // Optional name of the config.
  defaultAxis: 'L0', // Optional default axis. When an axis is not specified in commands, this axis is used.
  frequency: 50,     // Optional. The frequency of updates to devices in Hz. The default is 50.
  axes: [{
    name: 'L0',
    type: 'linear',
    alias: 'stroke'
    name: 'R1',
    type: 'rotation'
    alias: 'roll'

const ayva = new Ayva(config);