Bed.Sense Occupancy Sensor
Control4 Driver - Product 1.1.1, driver version 6
.Origami Intelligence, LLC - Making smart-home, intelligent

WHAT IT DOES

Bed.Sense reports whether a bed is occupied. That is all it does.

A pressure mat is a noisy switch. It releases when a sleeper rolls over and it
releases when someone goes to the bathroom. Wired straight to a contact input,
that noise reaches your programming and scenes misfire. This driver filters
the noise and gives you two clean signals from one mat: a fast one and a slow
one.

The driver holds no opinion about when anyone sleeps. There are no time
periods and no schedule in this driver. Schedule in Composer, where the
household's own hours belong.

  All logic runs on the controller. No cloud service, no network
  connection, no radio, no app.


HARDWARE

Parameter              Value
------------------------------------------------------------------------------
Contact form           Normally Open
Activation             16 kg
Operating pressure     25 kg over 50 mm2
Switching voltage      25 VDC maximum
Switching current      0.25 A DC maximum, resistive
Switching load         10 W/VA maximum
Contact resistance     1 ohm typical
Ingress protection     IP64. Not waterproof.
Operating temperature  -10 C to 70 C
Mat material           Seam-welded PVC
Cable                  0.22 mm2, black PVC insulated

The mat is rated well above the low-voltage sense current of a Control4
contact input. No interface relay is necessary.


INSTALLATION

1. Place the mat under the mattress, centered on the torso position. Not
   under the legs, and not under the pillow.
2. Land the two mat conductors on a contact input on a Control4 controller
   or a contact/relay extender. Polarity does not matter.
3. Add the Bed.Sense driver to the bedroom.
4. In Connections, bind Bed Mat Contact Input to the contact input you
   used.
5. Apply weight to the mat and confirm the Contact State property changes.
6. Prove your programming with the Actions tab: Simulate Bed Occupied and
   Simulate Bed Vacated fire the same events the mat fires.

Connections
-----------
Bed Mat Contact Input
  Direction : Input
  Purpose   : Bind to the physical contact input the mat is
              landed on.

Bed Occupied Output
  Direction : Output
  Purpose   : Settled occupancy, after debounce and dwell.


Bed.Sense has no Navigator interface. It is a background logic device. If the
customer wants bed state visible on a touch screen, bind Bed Occupied Output
to a stock Control4 contact sensor driver and let that driver present it.


THE THREE TIMERS

Enter Debounce
  Default      : 5 s
  What it does : The mat must stay pressed this long before
                 Bed Occupied fires.

Exit Debounce
  Default      : 3 s
  What it does : The mat must stay released this long
                 before Brief Exit Started fires.

Exit Dwell
  Default      : 120 s
  What it does : The mat must stay released this long
                 before Bed Vacated fires.


Enter Debounce rejects a person sitting on the edge of the bed. Exit Debounce
rejects a weight shift or a roll-over. Exit Dwell decides how long someone
must be off the mat before they count as having left.

Returning to bed
----------------
Enter Debounce does a second job. When the mat is loaded again during an exit
dwell, the return must hold for Enter Debounce before the driver accepts it
and fires Brief Exit Cancelled.

While the driver waits for that confirmation, the exit dwell is suspended, not
restarted. If the mat releases again, the dwell resumes with the time it had
left. A bouncing contact, or a duvet settling back onto an empty mat,
therefore cannot postpone Bed Vacated. Bed Vacated always lands one Exit Dwell
after the customer actually left.

Misconfiguration
----------------
Exit Debounce must be less than Exit Dwell. If it is not, the driver writes an
error to the Control4 log and suppresses Brief Exit Started rather than firing
it out of order. Setting Exit Dwell to 0 turns off filtering on the release
edge entirely; that is a legal configuration and is not reported as an error.


FAST SIGNAL AND SLOW SIGNAL

One mat, two usable signals. This is the whole point of the driver.

Speed
  Brief Exit Started : Fast. 3 s after the mat
                       releases.
  Bed Vacated        : Slow. 120 s after the mat
                       releases.

Means
  Brief Exit Started : Somebody got off the mat.
  Bed Vacated        : Somebody left, and stayed
                       gone.

Where they are
  Brief Exit Started : Still standing next to the
                       bed.
  Bed Vacated        : Out of the room.

Use it for
  Brief Exit Started : Path lighting, night lighting,
                       a bathroom scene.
  Bed Vacated        : Wake scenes, HVAC setback,
                       shades, whole-house modes.

If they come back
  Brief Exit Started : Brief Exit Cancelled fires
                       instead.
  Bed Vacated        : It never fired.


Use the fast signal for anything that must respond while the customer is still
beside the bed. Use the slow signal for anything a bathroom trip must never
trigger.


PROGRAMMING EVENTS

Event                 Fires when
------------------------------------------------------------------------------
Bed Occupied          The mat has been pressed for Enter
                      Debounce.
Bed Vacated           The mat has been released for Exit
                      Dwell.
Brief Exit Started    The mat has been released for Exit
                      Debounce. The dwell is running.
Brief Exit Cancelled  The customer returned and stayed
                      for Enter Debounce, before the
                      dwell expired.

Nothing fires on a Director restart. When the driver starts, it adopts
whatever state the contact input reports and tells no one, so a reboot never
re-runs a sleep scene.


VARIABLES

OCCUPIED
  Type    : BOOL
  Meaning : Settled occupancy.

RAW_CONTACT
  Type    : BOOL
  Meaning : Unfiltered contact state, after the wiring-style
            inversion.

OCCUPIED_MINUTES
  Type    : NUMBER
  Meaning : Minutes since the bed became occupied.

EMPTY_MINUTES
  Type    : NUMBER
  Meaning : Minutes since the bed became empty.

PENDING_STATE
  Type    : STRING
  Meaning : None, Occupying, or Vacating.


The duration counters update on a 30 second tick, so they can lag the true
elapsed time by up to 30 seconds. Both counters read 0 until the driver has
seen the mat for the first time; read the Contact State property, which says
Unknown until then, if you need to know whether the driver has heard from the
mat at all.


EXAMPLE PROGRAMMING

Path lighting on a night bathroom trip
--------------------------------------
  WHEN  Bed.Sense -> Brief Exit Started
  IF    the time is between 22:00 and 06:00
  THEN  set Hall Lights to 10 percent

  WHEN  Bed.Sense -> Brief Exit Cancelled
  THEN  turn off Hall Lights

Wake scene
----------
  WHEN  Bed.Sense -> Bed Vacated
  IF    the time is between 05:00 and 10:00
  THEN  activate the Good Morning scene

Sleep scene
-----------
  WHEN  Bed.Sense -> Bed Occupied
  IF    the time is between 21:00 and 02:00
  THEN  activate the Goodnight scene

Use the Scheduler agent or a time conditional for anything time based. The
household decides its own hours, not this driver.


TROUBLESHOOTING

Symptom                     Do this
------------------------------------------------------------------------------
The bed never reads occupi  Check the Contact
                            State property. If it
                            never changes, the
                            wiring or the contact
                            input binding is
                            wrong. Confirm the
                            occupant weight over
                            the mat area is above
                            16 kg, and that the
                            mat is under the
                            torso.
The bed reads occupied all  Check the Contact
                            Style property.
                            Bed.Sense mats are
                            Normally Open.
Scenes trigger when the cu  Increase Enter
                            Debounce.
Path lighting flickers whe  Increase Exit
                            Debounce.
The sleep scene cancels du  Increase Exit Dwell.
Brief Exit Cancelled feels  Decrease Enter
                            Debounce. It is the
                            return confirmation
                            window as well as the
                            entry filter.
The wake scene is too slow  Program on Brief Exit
                            Started with a time
                            conditional instead of
                            Bed Vacated, or
                            decrease Exit Dwell.

For diagnostics, set Log Mode to Print and Log and Log Level to 4 - Debug,
then watch the Lua output window in Composer Pro. Print Driver State in the
Actions tab dumps the full state machine, including how much of the exit dwell
is left.


RELEASE NOTES

1.1.1 - driver version 6
------------------------
- Device icon paths restored to the archive-root form that Composer
   resolves. The 16x16 and 32x32 device icons now ship at both icons/ and
   www/icons/, so the Bed.Sense art is found either way. 1.1.0 pointed
   them at www/icons/ only and Composer fell back to a stock Control4 icon
   in the project tree.

1.1.0 - driver version 5
------------------------
- A brief return to the mat no longer restarts the exit dwell. A
   chattering contact could previously postpone Bed Vacated indefinitely
   and repeat Brief Exit Started and Brief Exit Cancelled at programming.
- A return to bed is now confirmed over Enter Debounce before Brief Exit
   Cancelled fires, so a roll-over cannot produce a Started and Cancelled
   pair.
- The first contact report is only adopted silently when it is a state
   sync. A genuine change now runs the normal Enter Debounce, so the first
   person into the bed produces Bed Occupied, and the Simulate actions
   fire real events for commissioning.
- Contact Style is recomputed from the stored contact state instead of
   being toggled, so a repeated property notification can no longer invert
   a live system. A wiring-style edit is adopted silently and never runs a
   scene.
- Exit Debounce 0 with Exit Dwell 0 no longer writes a false
   configuration error to the Control4 log.

1.0.0 - driver version 4
------------------------
- First release. Enter Debounce, Exit Debounce and Exit Dwell, four
   events, five variables, no schedule.


SUPPORT

.Origami Intelligence, LLC - Making smart-home, intelligent

Distributed through DriverCentral. Dealer channel only.

Patent pending US 63/907,698.
