Module: j5e/servo

Description

A module for controlling hobby servos and continuous rotation servos using PWM servo control.

A servomotor is a rotary actuator or linear actuator that allows for precise control of angular or linear position, velocity and acceleration. It consists of a suitable motor coupled to a sensor for position feedback. It also requires a relatively sophisticated controller, often a dedicated module designed specifically for use with servomotors.Read more on Wikipedia

Servo control is a method of controlling many types of RC/hobbyist servos by sending the servo a PWM signal, a series of repeating pulses of variable width where either the width of the pulse or the duty cycle of a pulse train determines the position to be achieved by the servo. The PWM signal might come from a radio control receiver to the servo or from common microcontrollers such as the Arduino.Read more on Wikipedia

Pulse-width modulation (PWM), or pulse-duration modulation (PDM), is a method of reducing the average power delivered by an electrical signal, by effectively chopping it up into discrete parts. The average value of voltage fed to the load is controlled by turning the switch between supply and load on and off at a fast rate. The longer the switch is on compared to the off periods, the higher the total power supplied to the load. Along with maximum power point tracking (MPPT), it is one of the primary methods of reducing the output of solar panels to that which can be utilized by a battery. PWM is particularly suited for running inertial loads such as motors, which are not as easily affected by this discrete switching, because their inertia causes them to react slowly. The PWM switching frequency has to be high enough not to affect the load, which is to say that the resultant waveform perceived by the load must be as smooth as possible.Read more on Wikipedia

Requires

Class: Servo

The Servo class allows for control of hobby servos

Constructor

new Servo(io)

Parameters

Name
Type
Description
io
(required)
number, string, or object

Description:
 Pin identifier or IO Options (See instantiation)

Example

// Sweep a servo back and forth
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.sweep();

Properties

Name
Type
Description
history
(read only)
The last five position updates
last
(read only)
The most recent position update
position
(read only)
The most recent request and corrected position (factors in offset and invert)

Events

  • move:complete - Fires when a servo reaches its requested position

Methods

Servo.configure

Configure a Servo

servo.configure(options);

Returns: The instance on which the method was called

Parameters

Name
Type
Description
options
(required)
object

Description:
 Device configuration options

options.pin
number, or string

Description:
 If passing an object, a pin number or pin identifier

options.io
string, or constructor

Description:
 If passing an object, a string specifying a path to the IO provider or a constructor
Default: builtin/pwm

options.type
string

Description:
 Type of servo ("standard" or "continuous")
Default: "standard"

options.pwmRange
Array.<number>

Description:
 The pulse width range in microseconds
Default: [600, 2400]

options.deadband
Array.<number>

Description:
 The degree range at which a continuos motion servo will not turn
Default: [90,90]

options.range
Array.<number>

Description:
 The allowed range of motion in degrees
Default: [0, 180]

options.deviceRange
Array.<number>

Description:
 The physical range (throw) of the servo in degrees
Default: [0, 180]

options.startAt
number

Description:
 The desired start position of the servo
Default: "Any value within options.range"

options.offset
number

Description:
 Adjust the position of the servo for trimming
Default: 0

options.invert
boolean

Description:
 Reverses the direction of rotation

options.center
boolean

Description:
 Center the servo on instantiation

Example

// Move a continuos rotation servo forward
import Servo from "j5e/servo";

const servo = await new Servo({ pin: 12 });
servo.configure({type: "continuous"});
servo.cw();

Servo.initialize

Note: This method is not part of the public API, and is subject to change.

The initialization code for a servo

servo.initialize();

Servo.update

Note: This method is not part of the public API, and is subject to change.

Calls the write param on the IO instance for this servo.

servo.update(pulseWidth);

Returns:

Parameters

Name
Type
Description
pulseWidth
(required)
number

Description:
 The target pulseWidth

Servo.to

Set the servo's position to given degree over time.

servo.to(degrees, time, rate);

Returns: instance

Parameters

Name
Type
Description
degrees
(required)
Number, or Object

Description:
 Degrees to move servo to or an animation object (See animation)

time
Number

Description:
 Time to spend in motion. If degrees is a number and this value is ommitted, the servo will move to the requested degrees as quickly as possible.

rate
Number

Description:
 The target frame rate of the motion transiton
Default: 20

Example

// Move a servo to 180° as quickly as possible
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.to(180);

Example

// Move a servo to 180° over one second
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.to(180, 1000);

Example

// Move a servo to 180° using an animation segment object
import Servo from "j5e/servo";
import { inOutQuad } from "j5e/easing";

const servo = await new Servo(12);
servo.to({
  duration: 1000,
  cuePoints: [0, 1.0],
  keyFrames: [ null, 180 ],
  easing: inOutQuad
});

Servo.step

Update the servo position by specified degrees (over time)

servo.step(degrees, time);

Returns:

Parameters

Name
Type
Description
degrees
(required)
Number

Description:
 Degrees to turn servo to.

time
Number

Description:
 Time to spend in motion.

Example

// Move a servo to 120° as quickly as possible
import Servo from "j5e/servo";

const servo = await new Servo(12);
// The servo's default position is 90 degrees
servo.step(30);

Example

// Move a servo to 120° over one second
import Servo from "j5e/servo";

const servo = await new Servo(12);
// The servo's default position is 90 degrees
servo.step(30, 1000);

Servo.min

min Set Servo to minimum degrees, defaults to 0deg

servo.min(time);

Returns:

Parameters

Name
Type
Description
time
Number

Description:
 Time to spend in motion.

Example

// Move a servo to 0° as quickly as possible
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.min();

Example

// Move a servo to 0° over one second
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.min(1000);

Servo.max

Set Servo to maximum degrees, defaults to 180deg

servo.max(time);

Returns: instance

Parameters

Name
Type
Description
time
Number

Description:
 Time to spend in motion.

Example

// Move a standard servo to 180° as quickly as possible
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.max();

Example

// Move a standard servo to 180° over one second
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.max(1000);

Servo.center

Set Servo to centerpoint, defaults to 90deg

servo.center(time);

Returns: instance

Parameters

Name
Type
Description
time
Number

Description:
 Time to spend in motion.

Example

// Move a servo to 180° and then back to 90° as quickly as possible
import Servo from "j5e/servo";
import { timer } from "j5e/fn";

const servo = await new Servo(12);
servo.to(180);

timer.setTimeout(function() {
  servo.center();
}, 1000);

Example

// Move a servo to 180° and then back to 90° over one second
import Servo from "j5e/servo";
import { timer } from "j5e/fn";

const servo = await new Servo(12);
servo.to(180);

timer.setTimeout(function() {
  servo.center(1000);
}, 1000);

Servo.home

Return Servo to its startAt position

servo.home();

Returns:

Example

// Move a servo to 180° and then back to 90° as quickly as possible
import Servo from "j5e/servo";
import { timer } from "j5e/fn";

const servo = await new Servo(12);
servo.to(180);

timer.setTimeout(function() {
  servo.home();
}, 1000);

Servo.sweep

Sweep the servo between min and max or provided range

servo.sweep(opts);

Returns:

Parameters

Name
Type
Description
opts
(required)
Array, or Object

Description:
 An array describing the range of the sweep in degrees or an animation segment options object

Example

// Sweep a servo back and forth between 10° to 170°
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.sweep([10, 170]));

example
// Sweep a servo back and forth between 10° to 170° with inOutCirc easing
import Servo from "j5e/servo";
import {inOutCirc} from "j5e/easing";

const servo = await new Servo(12);
servo.sweep({
  keyFrames: [10, 170],
  cuePoints: [0, 1],
  easing: inOutCirc
});

Servo.stop

Stop a moving servo return {Servo}

servo.stop();

Example

// Sweep a servo back and forth for two seconds then stop
import Servo from "j5e/servo";

const servo = await new Servo(12);
servo.sweep([10, 170]));

timer.setTimeout(function() {
  servo.stop();
}, 2000);

Servo.cw

Move a continuous rotation servo clockwise

servo.cw(speed);

Returns:

Parameters

Name
Type
Description
speed
(required)
number

Description:
 Speed between 0 and 1.
Default: 1

Example

// Move a continuos rotation servo clockwise
import Servo from "j5e/servo";

const servo = await new Servo({ pin: 12, type: "continuous"});
servo.cw();

Example

// Move a continuos rotation servo clockwise at half speed
import Servo from "j5e/servo";

const servo = await new Servo({ pin: 12, type: "continuous"});
servo.cw(0.5);

Servo.ccw

Move a continuous rotation servo counter-clockwise

servo.ccw(speed);

Returns:

Parameters

Name
Type
Description
speed
(required)
number

Description:
 Speed between 0 and 1.
Default: 1

Example

// Move a continuos rotation servo counter-clockwise
import Servo from "j5e/servo";

const servo = await new Servo({ pin: 12, type: "continuous"});
servo.ccw();

Example

// Move a continuos rotation servo counter-clockwise at half speed
import Servo from "j5e/servo";

const servo = await new Servo({ pin: 12, type: "continuous"});
servo.ccw(0.5);

Servo.normalize

Note: This method is not part of the public API, and is subject to change.

servo.normalize(number || object);

Parameters

Name
Type
Description
number || object

Description:
 keyFrames An array of step values or a keyFrame objects

Servo.render

Note: This method is not part of the public API, and is subject to change.

render

servo.render();

Servo.on

Create an event listener

servo.on(event, listener);

Parameters

Name
Type
Description
event
(required)
string

Description:
 The name of the event to listen for

listener
(required)
function

Description:
 A callback to run when the event is fired.

Servo.removeListener

Remove an event listener

servo.removeListener(event, listener);

Parameters

Name
Type
Description
event
(required)
string

Description:
 The name of the event that we are removing a listener from

listener
(required)
function

Description:
 The callback that we are removing

Servo.emit

Note: This method is not part of the public API, and is subject to change.

Emit an event

servo.emit(event);

Parameters

Name
Type
Description
event
(required)
string

Description:
 The name of the event to emit

Servo.once

Create an event listener that will only fire one time.

servo.once(event, listener);

Parameters

Name
Type
Description
event
(required)
string

Description:
 The name of the event to listen for

listener
(required)
function

Description:
 A callback to run when the event is fired.