ParticleGarage (community library)

Summary

Example Build Testing

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

ParticleGarage

A Particle library for ParticleGarage automates the monitoring and remote-control of a garage door with a power opener.

Usage

Connect XYZ hardware, add the ParticleGarage library to your project and follow this simple example:

#include "ParticleGarage.h"
ParticleGarage particleGarage(D1, NORMALLY_OPEN, D2, NORMALLY_OPEN, D0, UnusedPin, NORMALLY_CLOSED, D4, 0);

void setup() {
particleGarage.Init("Garage", D1, NORMALLY_OPEN, D2, NORMALLY_OPEN, D0, UnusedPin, NORMALLY_CLOSED, D4, 0););
}

void loop() {
particleGarage.loop();
}

See the examples folder for more details.

Documentation

The garage door state is monitored by two proximity switches (i use reed relays and a magnet attached to the garage door - but other limit switches could be used): openPin - detects when the door is in the fully opened position closePin - detects when the door is in the fully closed position

To make the limit switches resilient to noise and bouncing (there tends to be a lot of vibration when the garage door is moving), the switch readings are sampled at a fixed 100ms interval using a timer and debounced using a simple bit shift register.

The pulsePin, via a relay, is wired to the garage door opener pins (in parallel with any physical switches inside the garage) to open/close the door. The duration of the pulse is set by the PulseDuration() (default: 3 s). The RemoteControl() function

• Since the ParticleGarage knows if the door is opened or closed, the RemoteControl() function does not simply toggle the door, it commands the door to 'open' or 'close'.
• If the door is already in the correct position - it does nothing.
• If the warningPin is defined, the warningPin will be pulsed for the WarningTime (connect to a buzzer or flashing light) to warn anyone in the vicinity that the door is about to move prior to pulsing the pulsePin when the door is commanded to move remotely.

The position of the garage door is monitored and the state is updated whether the garage door opener is controlled by this system, via a manual button, or a car remote.

• PulseTime - the length of time that the pulse pin is activated to start moving the door; if the door does not start moving (openPin and closePin not active) then a warning that the door didn't move is raised.
• TravelTime - the length of time that the door should take to move from open to closed or vice versa; if a open or closed position is not reached in this amount of time, an error is raised and the door is pulsed once more to move it back to a good position; the travel time should be the time it takes to open and close the door to account for the door closing, hitting an obstacle, and re-opening. The actual open/close travel time is published as
• If the door does not move to a fully opened/closed position within a timeout period, an error is posted and the door opener is pulsed again to 'fix' the problem (i.e. get it back to a known position). The timeout is set by the TravelDuration() (default: 15 s).
• If the door automatically moves back to the position it started from (e.g. it was blocked or the trip sensor was triggered), an error is posted but the door is left in the position it achieved.

ParticleGarage can optionally be auto-closed after being open for a period of time (disabled by default). Setting the AutoCloseDuration() to a positive value enables the option.

• The auto-close duration can be extended by configuring the motionPin to be connected to a motion detector - whenever motion is detected, the auto-close timer is reset.
• An event is posted when the auto-close is activated to close the garage door.

Two remote integrations can be enabled for the garage door: Particle Cloud - raise events, configure, open/close, monitor 'live' state

• to enable, set publishToParticle to true in the Init() function. MQTT - raise events, configure, open/close, monitor 'live' state
• to enable, call MQTTConnect() with a valid instance of an MQTT client; call MQTTDisconnect() to disable/clean-up on shutdown

Contributing

Here's how you can make changes to this library and eventually contribute those changes back.

To get started, clone the library from GitHub to your local machine.

Change the name of the library in library.properties to something different. You can add your name at then end.

Modify the sources in and with the new behavior.

To compile an example, use particle compile examples/usage command in Particle CLI or use our Desktop IDE.

After your changes are done you can upload them with particle library upload or Upload command in the IDE. This will create a private (only visible by you) library that you can use in other projects. Do particle library add ParticleGarage_myname to add the library to a project on your machine or add the ParticleGarage_myname library to a project on the Web IDE or Desktop IDE.

At this point, you can create a GitHub pull request with your changes to the original library.

If you wish to make your library public, use particle library publish or Publish command.

LICENSE

Copyright 2020 Kevin Houston

Licensed under the license

Browse Library Files