The Proximity class constructs an object that represents a single Proximity sensor.

Supported Proximity sensors:

  • Pulse/PWM
  • Analog
    • Ultrasonic
      • MB1000, LV-MaxSonar-EZ0
        • Hardware Constraints
          • Range:
            • Close: 0-15cm (will result in 15cm reading)
            • Long: 15-645cm (15-50cm may experience acoustic phase cancellation)
          • Resolution: 2.54cm
        • Likely supports the entire LV-MaxSonar-EZ* line, additional sensors to be confirmed.
      • MB1010, LV-MaxSonar-EZ1
        • Hardware Constraints
          • Range:
            • Close: 0-15cm (will result in 15cm reading)
            • Long: 15-645cm
          • Resolution: 2.54cm
      • MB1003, HRLV-MaxSonar-EZ0
        • Hardware Constraints
          • Range:
            • Close: 0-30cm (will result in 30cm reading)
            • Long: 30-500cm
          • Resolution: 1cm
      • MB1230, XL-MaxSonar-EZ3
        • Hardware Constraints
          • Range:
            • Close: 0-20cm (will result in 20cm reading)
            • Long: 20-765cm
          • Resolution: 1cm
    • Infrared
      • GP2Y0A21YK
        • Hardware Constraints
          • Range:
            • Close: 0-10cm (will result in 10cm reading)
            • Long: 10-80cm
          • Resolution: 1cm
      • GP2D120XJ00F
        • Hardware Constraints
          • Range:
            • Close: 0-4cm (will result in 4cm reading)
            • Long: 4-30cm
          • Resolution: 1cm
      • GP2Y0A02YK0F
        • Hardware Constraints
          • Range:
            • Close: 0-15cm (will result in 15cm reading)
            • Long: 15-150cm
          • Resolution: 1cm
      • GP2Y0A41SK0F
        • Hardware Constraints
          • Range:
            • Close: 0-4cm (will result in 4cm reading)
            • Long: 4-30cm
          • Resolution: 1cm
      • GP2Y0A710K0F
        • Hardware Constraints
          • Range:
            • Close: 0-50cm (will result in 50cm reading)
            • Long: 50-500cm
          • Resolution: 1cm
  • I2C
    • Lidar
      • LIDAR-Lite
        • Hardware Constraints
          • Range:
            • Long: 0-4000cm
          • Resolution: < 1cm
    • Ultrasonic
      • SRF10
        • Hardware Constraints
          • Range:
            • Close: 0-6cm (will result in 6cm reading)
            • Long: 6-600cm
          • Resolution: < 1cm
      • [HCSR04 (or similar see above) using and I2C backpack]
        • Hardware Constraints
          • Additional hardware:
            • Requires addition of another board such as an Arduino Nano to provide the I2C support.
          • Range:
            • Close: 0-2cm (will result in 2cm reading)
            • Long: 2-300cm
          • Resolution: < 1cm

Parameters

  • options An object of property parameters.

    PropertyTypeValue/DescriptionDefaultRequired
    pinNumber, StringAnalog or Digital Pin. Use for non-I2C sensorsYes (non-I2C)
    controllerStringGP2Y0A21YK, GP2D120XJ00F, GP2Y0A02YK0F, GP2Y0A41SK0F, GP2Y0A710K0F, PING_PULSEIN *, MB1000, MB1003, MB1230, LIDARLITE. See aliasesYes
    freqNumberMilliseconds. The frequency in ms of data events.25msNo

    Controller Alias Table
    ControllerAlias
    GP2Y0A21YK2Y0A21
    GP2D120XJ00F2D120X
    GP2Y0A02YK0F2Y0A02
    GP2Y0A41SK0FOA41SK
    GP2Y0A21YK0A21
    GP2Y0A02YK0F0A02
    LV-MaxSonar-EZMB1000
    HRLV-MaxSonar-EZ0MB1003
    XL-MaxSonar-EZ3MB1230
    HC-SR04PING_PULSE_IN
    HCSR04PING_PULSE_IN
    SRF05PING_PULSE_IN
    PARALLAXPINGPING_PULSE_IN
    SEEEDPINGPING_PULSE_IN
    GROVEPINGPING_PULSE_IN
    LIDAR-LiteLIDARLITE

Shape

Property NameDescriptionRead Only
idA user definable id value. Defaults to a generated uidNo
cmDistance to obstruction in centimeters.Yes
centimetersDistance to obstruction in centimeters.Yes
inDistance to obstruction in inches.Yes
inchesDistance to obstruction in inches.Yes

Component Initialization

Analog GP2Y0A21YK (and friends)

/*
  Use with:

  - GP2Y0A21YK
  - GP2D120XJ00F
  - GP2Y0A02YK0F
  - GP2Y0A41SK0F
*/

new five.Proximity({
  controller: "GP2Y0A21YK",
  pin: "A0"
});

Proximity

Analog GP2Y0A710K0F

new five.Proximity({
  controller: "GP2Y0A710K0F",
  pin: "A0"
});

Proximity

HCSR04/Parallax Ping *

new five.Proximity({
  controller: "HCSR04",
  pin: 7
});

Ping

* For Arduino boards, it is absolutely REQUIRED to flash your board with a special version of StandardFirmata (PingFirmata). Instructions are here.

Alternatively also consider an I2C Backpack which will keep your firmata the same and allow you to use this sensor on alternative boards such as a Raspberry Pi, BeagleBone or other non-Arduino board.

HCSR04 (and friends) I2C Backpack *

new five.Proximity({
  controller: "HCSR04I2CBACKPACK",
});

Ping

The I2C backpack requires using an Arduino (eg Nano or pro-mini) to provide the I2C capability. This removes the blocking behaviour of the PingFirmata firmware and makes this sensor more portable across alternative boards (anything that has I2C support in its IO plugin). See NodeBots Interchange HC-SR04 module for more details.

MB1000 LV-MaxSonar-EZ0
new five.Proximity({
  controller: "MB1000",
  pin: "A0"
});
MB1003 HRLV-MaxSonar-EZ0
new five.Proximity({
  controller: "MB1003",
  pin: "A0"
});
MB1230 XL-MaxSonar-EZ3
new five.Proximity({
  controller: "MB1230",
  pin: "A0"
});

Sonar

LIDAR-Lite

new five.Proximity({
  controller: "LIDARLITE"
});

LIDAR

SRF10

new five.Proximity({
  controller: "SRF10"
});

SRF10

Usage

var five = require("johnny-five");
var board = new five.Board();

board.on("ready", function() {
  var proximity = new five.Proximity({
    controller: ...,
    pin: "A0"
  });

  proximity.on("data", function() {
    console.log("inches: ", this.inches);
    console.log("cm: ", this.cm);
  });
});

Events

  • data The "data" event is fired as frequently as the user defined freq will allow in milliseconds.

  • change The "change" event is fired when the distance to obstruction reading changes within the observable range of the sensor.

PingFirmata

DOES NOT APPLY TO NON-ARDUINO PLATFORMS

For use with:

The above listed devices require a special version of Firmata (shown below) to be loaded onto the Arduino in order to function properly. This is only necessary for the components listed in this section!

The most straightforward method to enabling this module is to use the Ping I2C Backpack. If you still want / need to use a custom firmata then the easiest way to get the firmata onto your board is to use interchange. Follow the directions below:

npm install nodebots-interchange

With your arduino plugged in then issue the following instruction, where is the serial port your arduino is plugged into (COM3, /dev/ttyUSB0 etc).

interchange install hc-sr04 -a uno -p <port> --firmata

The latest firmware will be downloaded and installed upon your board.

The final alternative is to copy and paste the source into the Arduino IDE and click the Upload button.

Examples

Hi! The Johnny-Five community is building new projects every day. We made this newsletter to tell you about what's new, what's good, and what's next for Open Source robotics. Join us in exploring what we can make together.

Fork me on GitHub