Module: j5e/motor

Description

A module for controlling electric motors by using PWM (Pulse Width Modulation) and digital pins to regulate the speed and direction of the motor. While it is possible to wire a (tiny) motor directly to your microcontroller, it is best to use a motor controller, which allows for higher voltages and current.

An electric motor is an electrical machine that converts electrical energy into mechanical energy. Most electric motors operate through the interaction between the motor's magnetic field and electric current in a wire winding to generate force in the form of torque applied on the motor's shaft. An electric generator is mechanically identical to an electric motor, but operates with a reversed flow of power, converting mechanical energy into electrical energy.Read more on Wikipedia

A motor controller is a device or group of devices that can coordinate in a predetermined manner the performance of an electric motor. A motor controller might include a manual or automatic means for starting and stopping the motor, selecting forward or reverse rotation, selecting and regulating the speed, regulating or limiting the torque, and protecting against overloads and electrical faults. Motor controllers may use electromechanical switching, or may use power electronics devices to regulate the speed and direction of a motor.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: Motor

The Motor class allows for control of non-directional DC Motors

Constructor

new Motor(io)

Parameters

Name
Type
Description
io
(required)
number, string, Array.<number>, Array.<string>, Array.<object>, or object

Description:
A pin identifier or motor IO options object (See instantiation)

Examples

// Using a pin number
import Motor from "j5e/motor";

const motor = await new Motor(12);
motor.fwd();
// Using an options object
import Motor from "j5e/motor";

const motor = await new Motor({
  pin: 12
});
motor.fwd();

Properties

Name
Type
Description
isOn
(read only)
boolean
This does not necessarily mean the motor is turning.
currentSpeed
(read only)
number
The Motor's current speed
enabled
(read only)
boolean
Whether the motor is enabled
direction
(read only)
boolean
The current direction

Methods

Motor.configure

Configure a Motor

motor.configure(options);

Returns: The instance on which the method was called

Parameters

Name
Type
Description
options
(required)
object

Description:
Device configuration options

options.enabled
boolean

Description:
Sets the enabled state of a motor
Default: true

options.threshold
number

Description:
The minimum speed [0, 1] that will make the motor move
Default: 0.11

options.invertPWM
boolean

Description:
When true, PWM values will be inverted when directional motor is in reverse

Example

import Motor from "j5e/motor";

const motor = await new Motor(12);
motor.configure({
  enabled: false
});
motor.forward(); // No signal is sent

Motor.enable

Enable a motor. If there is an enable pin, set its value to high

motor.enable();

Returns:

Example

// Enable a motor
import Motor from "j5e/motor";
import {timer} from "j5e/fn";

const motor = await new Motor([13, 12]);
motor.disable();
timer.setTimeout(() => {
  motor.enable();
}, 5000);

Motor.disable

Disable a motor. If there is an enable pin, set its value to low

motor.disable();

Returns:

Example

// Disable a motor
import Motor from "j5e/motor";

const motor = await new Motor([13, 12]);
motor.disable();

Motor.start

Start the motor

motor.start(speed);

Returns:

Parameters

Name
Type
Description
speed
(required)
number

Description:
Speed [0, 1]


Motor.stop

Stop the motor

motor.stop();

Returns:


Motor.resume

Resumes moving the motor after stop, brake or disable at the most recent set speed

motor.resume();

Returns:


Motor.brake

Brakes the motor - Note that not all motor controllers support braking. If there is no brake pin, brake() behaves the same as stop() and the motor will coast to a stop

motor.brake(duration);

Returns:

Parameters

Name
Type
Description
duration
number

Description:
Time in millseconds to hold the brake


Motor.release

Releases the brake and calls resume

motor.release();

Returns:


Motor.fwd

Alias to forward

motor.fwd();

Returns:


Motor.forward

Set the motor to spin forward. Note that "forward" is an arbitrary label. What it really means is that if they exist, the dir pin will be set low and cdir will be set high

motor.forward(speed);

Returns:

Parameters

Name
Type
Description
speed
number

Description:
The speed expressed as a value from 0 to 1
Default: 1


Motor.rev

Alias to reverse

motor.rev();

Returns:


Motor.reverse

Set the motor to spin in reverse. Note that "reverse" is an arbitrary label. What it really means is that if they exist, the dir pin will be set high and cdir will be set low

motor.reverse(speed);

Returns:

Parameters

Name
Type
Description
speed
number

Description:
The speed expressed as a value from 0 to 1
Default: 1