README.md 6.75 KB
Newer Older
1
![avm-trigger-daemon](docs/assets/logo-project.png)
2 3 4 5

This project targets the tracking of a human motion to trigger an action on an
AVM Smart Home actor. When a motion is detected, a light sensor can be checked
for the current ambient light level and if a configured threshold is passed,
6
the configured actor will be turn on for example. The `avm-motion-triggerd`
7 8 9 10 11 12 13
daemon can be configured to send user defined actions, like turn an actor on,
off or just toggle it.

- [About the setup](#about-the-setup)
- [Requirements](#requirements)
- [Installation](#installation)
  - [From Source](#from-source)
14
  - [Arch Linux Packaging](#arch-linux-packaging)
15 16 17 18 19 20
- [Configuration](#configuration)
  - [Service](#service)
  - [Process management](#process-management)
- [Development](#development)

## About the setup
21

22 23 24 25 26 27 28 29
The project runs productive on a [Raspberry Pi Model B rev2][] with [Arch Linux
ARM][] as distribution. For detecting human motions the [PIR Motion Sensor from
Seeed Studio][] was used.  The [Light Sensor Brick from ITead Studio][] was
used to detect the ambient light level. This sensor was attached to an
[MCP3008, 10 Bit / 8 Channel ADC][] which is connected via the SPI bus to the
Raspberry Pi. For further details consider the [Platform and Wiring][] wiki
page.

30 31 32 33 34
The project targets the [AVM Smart Home Solutions][]. The productive setup uses
a [AVM FRITZ!Powerline 546E][] power adapter as actor and a [AVM FRITZ!Box Fon
WLAN 7360 SL][] as router. It should also be possible to use the power adapter
standalone.

35
## Requirements
36

37
The project needs the following libraries to build:
38 39 40 41 42 43 44 45

* [glibc](https://www.gnu.org/software/libc/) (>=2.20)
* [openssl](https://www.openssl.org/) (>=1.0.1.l)
* [libxml2](http://www.xmlsoft.org/) (>=2.9.2)
* [libcurl](http://curl.haxx.se/libcurl/) (>=7.40.0)
* [libconfig](http://www.hyperrealm.com/libconfig/) (>=1.5)
* [libbcm2835](http://www.airspayce.com/mikem/bcm2835/) (>=1.46)

46 47
The versions behind the libraries are describing the lowest tested versions. Is it
possible that lower and/or higher versions will run fine, too.
48 49 50

The project was successfully compiled with the [GCC](https://gcc.gnu.org/) (>=4.9.2).

51
## Installation
52

53
### From Source
54

55
For all non-Arch Linux systems you can install the software the old way by
56 57 58 59 60 61 62 63 64 65 66 67 68
building it from source (`make build`) and fire a `make install`. The project
is not configured by autotools, but the makefiles makes use of the [standard
directory variables][]. Forthermore you can specify a `DESTDIR` variable for
packaging.  (`make DESTDIR=/tmp/xyz install`) If you are interessested in
changing the default directory variables consider the [Makefile.shared
file](Makefile.shared). They are change able the same way as `DESTDIR`. The
`uninstall` target takes care of the same variables and will cleanup your
system if you don't want the software to be installed.

:warning: This process expects you to build the software on the same
architecture as it will run on. For cross compiling consider a related guide
for your target architecture.

69
### Arch Linux Packaging
70

71
If you are interessested in building an Arch Linux package, all you have to do
72 73 74 75 76 77
is to clone this repository, install/build all the dependencies of the project
and run `makepkg` inside the `dist/archlinux` directory. Afterwards you will
find a fresh package (`avm-motion-trigger-*-*.pkg.tar.xz`) in the same
directory. This process underlies the same cross compiling restrictions as the
[From Source](#from-source) installation.

78
## Configuration
79

80
### Service
81

82 83
The [avm-motion-triggerd][] daemon can be configured with a configuration file
which follows the format which is described by the [avm-motion-trigger.conf][]
84
man page.  On Arch Linux the system wide configuration can be found at
85 86
`/etc/avm-motion-trigger.conf`.

87
### Process management
88

89 90 91 92 93 94
The [avm-motion-triggerd][] daemon can be started in different flavors. It is
able to run in foreground by adding the `-f|--foreground` parameters or in
background (without additional parameters).  While the daemon is running in
foreground, all logging outputs will be printed to `stdout` and/or `stderr`.
The foreground logging is prefixed with the current date/time and the log level
for the message. While the daemon runs in background, all logging outputs will
95
be redirected to `syslog`.  For Arch Linux there is a systemd unit file shipped
96 97
for the daemon. The service can be enabled with:
`sudo systemctl enable avm-motion-triggerd.service`.
98

99
## Development
100

101 102
The project is written in C and comes with a bulk of predefined GNU Make
targets to speed up common development tasks. To get in touch just fork and
103
clone the project, install/build the required dependencies and fire a `make build`.
104 105 106

The most adorable targets are `clean build test` (in this order :)). While
editing the man pages you can easily review the latest state with the `docs-*`
107 108
targets. (currently there are:
`docs-avmctl.1 docs-avm-motion-trigger.conf.5 docs-avm-motion-triggerd.1`)
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129

The project comes with a whole bunch of simple test binaries which covers
single aspects of the project en bloc.  All test cases can be easily accessed
with their corresponding `test-*` and `test-mem-*` targets. The `test-mem-*`
variants will be checked for memory leaks by valgrind. Here is a list of the
currently available GNU Make targets:

```
test-ambient-light-level test-build-url test-config test-list-switches
test-logger test-login test-mem-ambient-light-level test-mem-build-url
test-mem-config test-mem-list-switches test-mem-logger test-mem-login
test-mem-password-challenge test-mem-password-response test-mem-pidfile
test-mem-pir-motion-detection test-mem-switch-off test-mem-switch-on
test-mem-switch-toggle test-password-challenge test-password-response
test-pidfile test-pir-motion-detection test-switch-off test-switch-on
test-switch-toggle
```

Please mind the [Contribution Guide][] and the given [.editorconfig file][] if
you plan to work on the project.

130 131
[avm-motion-triggerd]: ../../wikis/man/avm-motion-triggerd.1.html
[avm-motion-trigger.conf]: ../../wikis/man/avm-motion-trigger.conf.5.html
132
[Platform and Wiring]: ../../wikis/platform-and-wiring
133 134
[Contribution Guide]: CONTRIBUTING.md
[.editorconfig file]: .editorconfig
135
[standard directory variables]: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
136 137 138 139 140
[Raspberry Pi Model B rev2]: https://www.raspberrypi.org
[Arch Linux ARM]: http://archlinuxarm.org/
[Light Sensor Brick from ITead Studio]: http://wiki.iteadstudio.com/Light_Sensor_Brick
[PIR Motion Sensor from Seeed Studio]: http://www.seeedstudio.com/wiki/PIR_Motion_sensor_module
[MCP3008, 10 Bit / 8 Channel ADC]: http://www.adafruit.com/products/856
141 142 143
[AVM Smart Home Solutions]: http://avm.de/ratgeber/smart-home/intelligentes-schalten/
[AVM FRITZ!Powerline 546E]: http://avm.de/produkte/fritzpowerline/fritzpowerline-546e/
[AVM FRITZ!Box Fon WLAN 7360 SL]: http://avm.de/produkte/fritzbox/fritzbox-7360/