`sensor.hcsr04`#

Description#

You can use this plugin to interact with a distance sensor on your Raspberry Pi. It’s been tested with a HC-SR04 ultrasound sensor, but it should be compatible with any GPIO-compatible sensor that relies on the same trigger-and-echo principle.

Configuration#

sensor.hcsr04:
  # [Required]
  # GPIO PIN where you connected your sensor trigger
  # PIN (the one that triggers the sensor to perform a measurement).
  trigger_pin:   # type=int

  # [Required]
  # GPIO PIN where you connected your sensor echo PIN (the
  # one that will listen for the signal to bounce back and therefore
  # trigger the distance calculation).
  echo_pin:   # type=int

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 0.25  # type=float

  # [Optional]
  # The echo-wait will terminate and the plugin will return
  # null if no echo has been received after this time (default: 1
  # second).
  # timeout: 2.0  # type=float

  # [Optional]
  # Number of seconds that should be waited on plugin
  # instantiation for the sensor to be ready (default: 2 seconds).
  # warmup_time: 2.0  # type=float

  # [Optional]
  # Custom `GPIO name` -> `PIN number` mapping. This can be
  # useful if you want to reference your GPIO ports by name instead
  # of PIN number.
  # pins:   # type=Optional[Dict[str, int]]

  # [Optional]
  # List of PINs to monitor. If a new value is detected
  # on these pins then a `GPIOEvent <https://docs.platypush.tech/platypush/events/gpio.html#platypush.message.event.gpio.GPIOEvent>`_
  # event will be triggered. GPIO PINS can be referenced either by number
  # or name, if a name is specified on the `pins` argument.
  # monitored_pins:   # type=Optional[Collection[Union[str, int]]]

  # [Optional]
  # Specify ``board`` if you want to use the board PIN numbers,
  # ``bcm`` for Broadcom PIN numbers (default: ``board``)
  # mode: board  # type=str

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

  # [Optional]
  # A number, numeric pair or mapping of ``str`` to
  # number/numeric pair representing the thresholds for the sensor.
  #
  # Examples:
  #
  #     .. code-block:: yaml
  #
  #         # Any value below 25 from any sensor will trigger a
  #         # SensorDataBelowThresholdEvent, if the previous value was
  #         # equal or above, and any value above 25 will trigger a
  #         # SensorDataAboveThresholdEvent, if the previous value was
  #         # equal or below
  #         thresholds: 25.0
  #
  #         # Same as above, but the threshold is only applied to
  #         # ``temperature`` readings
  #         thresholds:
  #             temperature: 25.0
  #
  #         # Any value below 20 from any sensor will trigger a
  #         # SensorDataBelowThresholdEvent, if the previous value was
  #         # equal or above, and any value above 25 will trigger a
  #         # SensorDataAboveThresholdEvent, if the previous value was
  #         # equal or below (hysteresis configuration with double
  #         # threshold)
  #         thresholds:
  #             - 20.0
  #             - 25.0
  #
  #         # Same as above, but the threshold is only applied to
  #         # ``temperature`` readings
  #         thresholds:
  #             temperature:
  #                 - 20.0
  #                 - 25.0
  # thresholds:   # type=Union[float, int, Tuple[Union[float, int], Union[float, int]], Mapping[str, Union[float, int, Tuple[Union[float, int], Union[float, int]]]], NoneType]

  # [Optional]
  # If set, then the sensor change events will be
  # triggered only if the difference between the new value and the
  # previous value is higher than the specified tolerance. For example,
  # if the sensor data is mapped to a dictionary::
  #
  #     {
  #         "temperature": 0.01,  # Tolerance on the 2nd decimal digit
  #         "humidity": 0.1       # Tolerance on the 1st decimal digit
  #     }
  #
  # Or, if it's a raw scalar number::
  #
  #     0.1  # Tolerance on the 1st decimal digit
  #
  # Or, if it's a list of values::
  #
  #     [
  #         0.01,   # Tolerance on the 2nd decimal digit for the first value
  #         0.1     # Tolerance on the 1st decimal digit for the second value
  #     ]
  # tolerance: 0  # type=Union[float, int, Mapping[str, Union[float, int]], Iterable[Union[float, int]]]

  # [Optional]
  # If `SensorPlugin.get_measurement <https://docs.platypush.tech/platypush/plugins/sensor.html#platypush.plugins.sensor.SensorPlugin.get_measurement>`_ returns a key-value
  # mapping, and ``enabled_sensors`` is set, then only the reported
  # sensor keys will be returned.
  # enabled_sensors:   # type=Optional[Iterable[str]]

Dependencies#

pip

pip install RPi.GPIO

Triggered events#

platypush.message.event.sensor.SensorDataChangeEvent

platypush.message.event.distance.DistanceSensorEvent

platypush.message.event.sensor.SensorDataBelowThresholdEvent

platypush.message.event.sensor.SensorDataAboveThresholdEvent

Actions#

sensor.hcsr04.cleanup

sensor.hcsr04.get_data

sensor.hcsr04.get_measurement

sensor.hcsr04.read

sensor.hcsr04.read_all

sensor.hcsr04.status

sensor.hcsr04.stop

sensor.hcsr04.write

Module reference#

class platypush.plugins.sensor.hcsr04.SensorHcsr04Plugin(*_, **__)[source]#

Bases: GpioPlugin, SensorPlugin

__init__(trigger_pin: int, echo_pin: int, poll_interval: float = 0.25, timeout: float = 2.0, warmup_time: float = 2.0, *args, **kwargs)[source]#

Parameters:

trigger_pin – GPIO PIN where you connected your sensor trigger PIN (the one that triggers the sensor to perform a measurement).
echo_pin – GPIO PIN where you connected your sensor echo PIN (the one that will listen for the signal to bounce back and therefore trigger the distance calculation).
timeout – The echo-wait will terminate and the plugin will return null if no echo has been received after this time (default: 1 second).
warmup_time – Number of seconds that should be waited on plugin instantiation for the sensor to be ready (default: 2 seconds).

cleanup()#: Cleanup the state of the GPIO and resets PIN values.

get_data(*args, **kwargs)#: (Deprecated) alias for get_measurement()

get_measurement(*_, **__) → float | None[source]#

Returns:: Distance measurement as a scalar (in mm):

main()#: Implementation of the main loop of the plugin.

Publishes a list of entities. The downstream consumers include:

The entity persistence manager

The web server

Any consumer subscribed to
platypush.message.event.entities.EntityUpdateEvent events (e.g. web clients)

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

read(pin: int | str, name: str | None = None) → Dict[str, Any]#

Reads a value from a PIN.

Parameters:

pin – PIN number or configured name.
name – Optional name for the read value (e.g. “temperature” or “humidity”)

Response:

output = {
    "name": <pin number or pin/metric name>,
    "pin": <pin>,
    "value": <value>,
    "method": "read"
}

read_all()#: Reads the values from all the configured PINs and returns them as a list. It will raise a RuntimeError if no PIN mappings were configured.

start()#: Start the plugin.

status(*_, **__) → float | int | Mapping[str, float | int] | Iterable[float | int] | None#: Returns the latest read values and publishes the platypush.message.event.entities.EntityUpdateEvent events if required.

stop()[source]#: Stop the plugin.

transform_entities(entities: float | None | Collection[float | None]) → List[DistanceSensor][source]#: This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)#: Wait until a stop event is received.

write(pin: int | str, value: int | bool, name: str | None = None) → Dict[str, Any]#

Write a byte value to a pin.

Parameters:

pin – PIN number or configured name
name – Optional name for the written value (e.g. “temperature” or “humidity”)
value – Value to write

Response:

output = {
    "name": <pin or metric name>,
    "pin": <pin>,
    "value": <value>,
    "method": "write"
}

sensor.hcsr04

Platypush documentation

sensor.hcsr04#

Description#

Configuration#

Dependencies#

Triggered events#

Actions#

Module reference#

`sensor.hcsr04`#