Arduino IDE: RBD_Light Example Blink Without DelayNeed help writing code? You can hire Robots + Big Data to write Arduino software for your project! Click here to get started...
Arduino

Human SensorAPI DOCUMENTATION

Detect human presence, touch, and pickup events.

See Example  Public Methods  Release Notes
Overview

Detect and interact with humans through change in capacitance. You can calibrate this library for your sensor very quickly to detect onNear()onTouch(), and onPickup() events. The example below uses a piece of aluminum foil, but you can attach the wire to anything conductive and calibrate the sensor accordingly.

This library measures relative capacitance so it is prone to interference. You can temporarily adjust the entire scale and then reset it when the capacitance disruption has stopped by using setModifier() and resetModifier(). Look at the Capacitance Library if you would like to know more about how capacitance is calculated.

Example Wiring
  1. Connect Arduino digital pin 2 to a 10MegΩ resistor
  2. Connect the other end of the 10MegΩ resistor to Arduino digital pin 3
  3. Connect Arduino digital pin 3 to a piece of conductive material (aluminum foil)
  4. Cover the conductive material with non-conductive material (tape)
  5. Load the Example Sketch onto the Arduino
  6. Open a serial connection at 115200 baud to see the reported values
  7. Calibrate the human sensor

A piece of aluminum foil connected to a 10 Meg Ohm resistor that is bridged across Arduino digital pins 2 and 3.

Example SketchArduinoC++
#include <RBD_Capacitance.h>
#include <RBD_Threshold.h>
#include <RBD_HumanSensor.h>

RBD::HumanSensor human_sensor(2, 3); // send, receive pin

void setup() {
  Serial.begin(115200);
  human_sensor.setNearValue(100);
  human_sensor.setTouchValue(200);
  human_sensor.setPickupValue(300);
}

void loop() {
  human_sensor.update();

  if(human_sensor.onGone()) {
    Serial.print("0. GONE   ");
  }
  else if(human_sensor.onNear()) {
    Serial.print("1. NEAR   ");
  }
  else if(human_sensor.onTouch()) {
    Serial.print("2. TOUCH  ");
  }
  else if(human_sensor.onPickup()) {
    Serial.print("3. PICKUP ");
  }

  if(human_sensor.onRawValueChange()) {
    Serial.println(human_sensor.getRawValue());
  }
}
Example Sketch Calibration

Follow these steps to calibrate each human sensor before use:

  1. Set up the human sensor then open a serial connection to the Arduino
  2. Move your hand just near the sensor to see the Raw Value change
  3. Change the setNearValue() to the Raw Value - in the example sketch setup()
  4. Touch the sensor to see the Raw Value change
  5. Change the setTouchValue() to the new Raw Value
  6. Pick up the sensor to see the Raw Value change (if it is attached to an object)
  7. Change the setPickupValue() to the new Raw Value
  8. Load the calibrated sketch back into the Arduino
  9. The human sensor is calibrated and ready to use
Public Methods

You must continuously call update() inside of loop() in order to use theReal-Time methods tagged below.

RBD::HumanSensor

RBD::HumanSensor constructor(send_pin, receive_pin)

Pass in integers for the send and receive pins to create a new instance of this class.

EXAMPLE SKETCH
RBD::HumanSensor human_sensor(2, 3);

void setup() {
  ...
}
human_sensor
.setSampleSize(value)

Pass in an integer to change the number of readings taken to calculate the moving average getRawValue(). This can be called inside of setup() or also safely at runtime inside of loop().

  • Decrease Variation in readings by making this number larger: 1000
  • Increase Variation in readings by making this number smaller: 10
  • Default Value: 250
EXAMPLE SKETCH
void setup() {
  human_sensor.setSampleSize(1000);
}
human_sensor
.setNearValue(value)

Provide an integer from getRawValue() to calibrate the lowest threshold for when a person is near the sensor.

EXAMPLE SKETCH
void setup() {
  human_sensor.setNearValue(100);
}
human_sensor
.setTouchValue(value)

Provide an integer from getRawValue() to calibrate the lowest threshold for when a person is touching the sensor.

EXAMPLE SKETCH
void setup() {
  human_sensor.setTouchValue(150);
}
human_sensor
.setPickupValue(value)

Provide an integer from getRawValue() to calibrate the lowest threshold for when a person is picking up the sensor.

EXAMPLE SKETCH
void setup() {
  human_sensor.setPickupValue(200);
}
human_sensor
.update()Update

Keep processing the readings and move this library along in real-time.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();
}
human_sensor
.isGone()Real-Time

Returns true if no human is present and the sensor is reading a value below the setNearValue(). This will always return true if no thresholds (near, touch, pickup) are set.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.isGone()) {
    ...
  }
}
human_sensor
.isNear()Real-Time

Returns true if a human is present and the sensor is reading a value at or above the setNearValue().

Returns false if the sensor is reading a value below the setNearValue(), or if a setTouchValue() has been assigned and the sensor is reading a value at or above the isTouch() value.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.isNear()) {
    ...
  }
}
human_sensor
.isTouch()Real-Time

Returns true if a human is touching the sensor and it is reading a value at or above the setTouchValue().

Returns false if the sensor is reading a value below the setTouchValue(), or if a setPickupValue() has been assigned and the sensor is reading a value at or above the isPickup() value.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.isTouch()) {
    ...
  }
}
human_sensor
.isPickup()Real-Time

Returns true if a human is picking up the sensor and it is reading a value at or above the setPickupValue().

Returns false if the sensor is reading a value below the setPickupValue().

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.isPickup()) {
    ...
  }
}
human_sensor
.onGone()Real-TimeEvent

This method will return true once the sensor registers a value below the setNearValue(). The active level must change away from and then come back to isGone() in order for this method to return true again.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onGone()) {
    // code only runs once per event
    Serial.println("Gone");
  }
}
human_sensor
.onNear()Real-TimeEvent

This method will return true once the sensor registers a value at or above the setNearValue() and below the setTouchValue(). The active level must change away from and then come back to isNear() in order for this method to return true again.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onNear()) {
    // code only runs once per event
    Serial.println("Near");
  }
}
human_sensor
.onTouch()Real-TimeEvent

This method will return true once the sensor registers a value at or above the setTouchValue() and below the setPickupValue(). The active level must change away from and then come back to isTouch() in order for this method to return true again.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onTouch()) {
    // code only runs once per event
    Serial.println("Touch");
  }
}
human_sensor
.onPickup()Real-TimeEvent

This method will return true once the sensor registers a value at or above the setPickupValue(). The active level must change away from and then come back to isPickup() in order for this method to return true again.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onPickup()) {
    // code only runs once per event
    Serial.println("Pickup");
  }
}
human_sensor
.getValue()Real-Time

Returns the capacitance sensor reading after being adjusted with the value given to setModifier().

This will return the raw capacitance sensor reading if you have not used setModifier() yet, or if you have called resetModifier().

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onValueChange()) {
    Serial.println(human_sensor.getValue());
  }
}
human_sensor
.getRawValue()Real-Time

Returns the raw capacitance sensor reading and ignores any value that has been passed to setModifier().

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  Serial.println(human_sensor.getRawValue());
}
human_sensor
.getActiveLevel()Real-Time

Returns the current sensor level after being adjusted by setModifier().

  •  0  no human is present
  •  1  a human is near
  •  2  a human is touching the sensor
  •  3  a human is picking up the sensor
  • -1  an error occured (non-continuous range)
EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  Serial.println(human_sensor.getActiveLevel());
}
human_sensor
.onValueChange()Real-TimeEvent

This method will return true once the getValue() changes.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onValueChange()) {
    // code only runs once per event
    Serial.println(human_sensor.getValue());
  }
}
human_sensor
.onRawValueChange()Real-TimeEvent

This method will return true once the getRawValue() changes.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onRawValueChange()) {
    // code only runs once per event
    Serial.println(human_sensor.getRawValue());
  }
}
human_sensor
.onActiveLevelChange()Real-TimeEvent

This method will return true once the getActiveLevel() changes.

EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(human_sensor.onActiveLevelChange()) {
    // code only runs once per event
    Serial.println(human_sensor.getActiveLevel());
  }
}
human_sensor
.setModifier(value)

Provide a positive or negative integer to temporarily adjust the human sensor threshold scale. The default value is 0.

For example; if you have calibrated the scale and turn on a motor near the sensor: all readings will need to be adjusted for the increased capacitance from the motor.

  • If a running motor increases the difference in human sensor readings by a getRawValue() of +200
  • Call setModifier(-200) on the human sensor when the motor turns on
  • All of the calibrated human sensor thresholds will adjust -200
  • The human sensor readings will account for motor interference
  • Call resetModifier() on the human sensor when the motor shuts off
EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(...) { // motor is on
    human_sensor.setModifier(-200);
  }
  else {
    human_sensor.resetModifier();
  }

  // when the motor is on; require +200 more from
  // the raw sensor reading to trigger all events
  if(human_sensor.isNear()) {
    ...
  }
  else if(...) {
    ...
  }
}
human_sensor
.resetModifier()

Changes the setModifier() back to 0 and resets calibration of the human sensor threshold scale.

For example; if you have calibrated the scale and turn on a motor near the sensor: all readings will need to be adjusted for the increased capacitance from the motor.

  • If a running motor increases the difference in human sensor readings by a getRawValue() of +200
  • Call setModifier(-200) on the human sensor when the motor turns on
  • All of the calibrated human sensor thresholds will adjust -200
  • The human sensor readings will account for motor interference
  • Call resetModifier() on the human sensor when the motor shuts off
EXAMPLE SKETCH
void loop() {
  human_sensor.update();

  if(...) {
    human_sensor.setModifier(-200);
  }
  else {  // motor is off
    human_sensor.resetModifier();
  }

  // when the motor is off; reset the
  // threshold values for all events
  if(human_sensor.isNear()) {
    ...
  }
  else if(...) {
    ...
  }
}