{"id":13631576,"url":"https://github.com/chollinger93/scarecrow","last_synced_at":"2026-01-08T12:59:48.055Z","repository":{"id":43234964,"uuid":"226762842","full_name":"chollinger93/scarecrow","owner":"chollinger93","description":"A Raspberry Pi powered, distributed (edge) computing camera setups that runs a Tensorflow object detection model to determine whether a person is on the camera. A plugin model allows actions based on the detection, such as playing audio, turning on lights, or triggering an Arduino.","archived":false,"fork":false,"pushed_at":"2023-10-04T00:52:29.000Z","size":1258,"stargazers_count":89,"open_issues_count":1,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-01T22:49:02.075Z","etag":null,"topics":["audio","debian","hacktoberfest","linux","machine-learning","network","opencv","opencv-python","raspberry","raspberry-pi","raspbian","tensorflow","zmq"],"latest_commit_sha":null,"homepage":"https://chollinger.com/blog/2019/12/tensorflow-on-edge-or-building-a-smart-security-camera-with-a-raspberry-pi/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chollinger93.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-12-09T01:53:50.000Z","updated_at":"2023-10-10T09:43:20.000Z","dependencies_parsed_at":"2024-01-19T11:26:10.321Z","dependency_job_id":null,"html_url":"https://github.com/chollinger93/scarecrow","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chollinger93%2Fscarecrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chollinger93%2Fscarecrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chollinger93%2Fscarecrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chollinger93%2Fscarecrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chollinger93","download_url":"https://codeload.github.com/chollinger93/scarecrow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223768519,"owners_count":17199356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","debian","hacktoberfest","linux","machine-learning","network","opencv","opencv-python","raspberry","raspberry-pi","raspbian","tensorflow","zmq"],"created_at":"2024-08-01T22:02:30.474Z","updated_at":"2026-01-08T12:59:47.982Z","avatar_url":"https://github.com/chollinger93.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Scarecrow-Cam\n![pytest](docs/tests.svg) ![covearge](docs/codecov.svg)\n\n## Maintenance \u0026 Project Status\n![https://img.shields.io/badge/Limited%20Maintenance%20Intended-x-important](https://img.shields.io/badge/Limited%20Maintenance%20Intended-x-important)\n\nThis project is in what I would describe as *\"Limited maintenance only\"* status. I'll continue to listen to CVE notifications and make sure you have some way of running it, but I don't intend on working on any major releases.\n\nThis project, at the time of writing, was a fun idea that used a somewhat novel approach to solve a real-life problem - a *showcase*, not a real, long-term project. But like so many tech showcases, that's all it is: Designed well enough to work and make a point, but not important enough to keep updated.\n\nSince writing this in 2019, things have moved on: This project depends on a very specific, old, and hence not necessarily well-performing `Tensorflow` model and was never designed to be containerized from the ground up, which makes the build and deployment process exceptionally brittle and, frankly, tedious to maintain. About half the dependencies called out in the [INSTALL.md](INSTALL.md) file are probably not actually needed.\n\nThere are also some (given the nature of a showcase, somewhat intentional) design oversights that *could* be mitigated, namely the weak abstraction at many points of the project, such as in the plugin model; while re-working those is certainly possible, it's not something I'll be spending any time on soon.\n\nLast but not least, there simply are better ways of deploying an object detection model on a Raspberry these days, such as [TensorFlow Lite](https://www.tensorflow.org/lite/tutorials) that allow you to run a model directly on the Pi. Local detection can still react accordingly to a detection threshold (which could be centrally managed, e.g. in a database) in the same way it does here, or even directly via GPIO. Nothing stops you from still maintaining a central point of accessing alerts from multiple cameras, but running the model locally will always outperform a network video stream.\n\n## Introduction\nA `Raspberry Pi` powered, distributed (edge) computing camera setups that runs a `Tensorflow` object detection model to determine whether a person is on the camera. The `Raspberry Pi` is used for video streaming and triggering actions (such as playing audio, turning on lights, or triggering an Arduino), whereas a server or laptop runs the object detection. With a suitable `TFLite` installation, this can happen locally on the `Raspberry` as well.\n\nBased on the detection criteria, a **plugin model** allows to trigger downstream actions.\n\n*Based on my [blog](https://chollinger.com/blog/2019/12/tensorflow-on-edge-or-building-a-smart-security-camera-with-a-raspberry-pi/).*\n\n\n# Architecture\n![Architecture](./docs/architecture.png)\n\n![Sample](./docs/cam_1.png)\n\n**Side note**: *The setup shown here only fits the use-case of `edge` to a degree, as we run local detection on a separate machine; technically, the Raspberry Pi is capable of running Tensorflow on board, e.g. through `TFLite` or `esp32cam`.*\n\n*You can change this behavior by relying on a local `tensorflor` instance and having the `ZMQ` communication run over `localhost`.*\n\n# Updates\nPlease see [CHANGELOG.md](./CHANGELOG.md) for details.\n\n# Configuration and data\n\nCopy `config/config.ini.sample` to `conf/config.ini` with the settings for your Raspberry and server.\n\nFor playing audio, please adjust `conf/plugins.d/audio.ini`.\n\n```\n[Audio]\nPath=../audio_files\n```\nFor an appropriate path.\n\nIf you want to change the `model`, please check the [Model Zoo](https://github.com/chollinger93/models/blob/master/research/object_detection/g3doc/detection_model_zoo.md). The blog article used the outdated `ssd_mobilenet_v1_coco_2017_11_17`.\n\n```\n[Tensorflow]\nModelUrl=ssd_mobilenet_v3_large_coco_2019_08_14\nLabelMapPath=./models/research/object_detection/data/mscoco_label_map.pbtxt\n```\n\n# Installing\n\n## Requirements\nThis project requires:\n* A Raspberry Pi + the camera module v2 (the `client`) \n* Any Linux machine on the same network (the `server`)\n\n![Pi](./docs/pi.jpg)\n\n\n## Using Docker (recommended)\n\n![Docker](./docs/horizontal-logo-monochromatic-white.png)\n\nUsing `Docker` is the preferred way of running `scarecrow`, as it handles dependencies internally and operates within a controllable environment.\n\n### Build Image\n```\ngit submodule update --init --recursive \u0026\u0026 git submodule update --remote\ndocker build . -t scarecrow\n```\n\n### Run separately\nBoth `client` and `server` containers should be ran separately.\n\n\n#### Server\nThis runs `tensorflow` and opens the `zmq` listener.\n```\ndocker run -it \\\n    --name scarecrow_server \\\n    -p 5455:5454 \\\n    --ipc=host \\\n    -v $(pwd)/conf:/config \\\n    -v $(pwd)/models/research/object_detection/data:/models \\\n    scarecrow \\\n    /usr/local/bin/scarecrow_server --config /config\n```\n\n#### Client\n*Check cameras in `/dev` with `ffplay /dev/video$x`*\n\n```\ndocker run -it \\\n    --name scarecrow_client \\\n    -p 5454:5454 \\\n    -p 5558:5558 \\\n    --ipc=host \\\n    -v $(pwd)/conf:/config \\\n    -v $(pwd)/resources/audio_files:/data \\\n    --device /dev/snd:/dev/snd \\\n    --device=/dev/video2:/dev/video0 \\\n    scarecrow \\\n    /usr/local/bin/scarecrow_client --config /config --input 0\n```\n\n### Docker Compose\n**Experimental**\n```\ndocker-compose up\n```\n\n## Manual install (advanced)\n`scarecrow-cam` can be installed using pip:\n```\npip3 install . --upgrade\n```\n\nPlease see [INSTALL.md](./INSTALL.md) for details and troubleshooting.\n\n### Run (RasPi)\n```\nscarecrow_client --config ./conf --input 0 # for picam\nscarecrow_client --config ./conf --input ./resources/tests/walking_test_5s.mp4 # for local video \n```\n\n### Run (Server)\n```\nscarecrow_server --config ./conf\n```\n\n# Plugins\nA plugin model allows to trigger downstream actions. These actions are triggered based on the configuration.\n\nPlugins can be enabled by setting the following in `config.ini`:\n```\n[Plugins]\nEnabled=audio\nDisabled=\n```\n\nCurrently, the following plugins are avaibale:\n\n| Plugin | Description                                 | Requirements                                 | Configuration              | Base  |\n|--------|---------------------------------------------|----------------------------------------------|----------------------------|-------|\n| `audio`  | Plays audio files once a person is detected | Either `playsound`, `pygame`, or `omxplayer` | `conf/plugins.d/audio.ini` | `ZMQ` |\n| `store_video`  | Stores video files on the server, with a defined buffer or length | `Path` and `Encoding` settings | `conf/plugins.d/store_video.ini` | `ZServerMQ` |\n\n# License\nThis project is licensed under the GNU GPLv3 License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchollinger93%2Fscarecrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchollinger93%2Fscarecrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchollinger93%2Fscarecrow/lists"}