{"id":13737626,"url":"https://github.com/jeffbass/yin-yang-ranch","last_synced_at":"2025-04-13T12:50:25.556Z","repository":{"id":113357777,"uuid":"127857098","full_name":"jeffbass/yin-yang-ranch","owner":"jeffbass","description":"Distributed Computer Vision Software \u0026 Raspberry Pis to help manage a farm","archived":false,"fork":false,"pushed_at":"2024-07-23T23:46:09.000Z","size":28100,"stargazers_count":93,"open_issues_count":3,"forks_count":21,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-27T03:51:17.286Z","etag":null,"topics":["imagezmq","opencv-python","python","pyzmq","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeffbass.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-03T05:46:25.000Z","updated_at":"2025-01-15T09:24:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"7c43e6b3-71f7-430d-9b4d-8f383b5e876f","html_url":"https://github.com/jeffbass/yin-yang-ranch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fyin-yang-ranch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fyin-yang-ranch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fyin-yang-ranch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fyin-yang-ranch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffbass","download_url":"https://codeload.github.com/jeffbass/yin-yang-ranch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717252,"owners_count":21150388,"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":["imagezmq","opencv-python","python","pyzmq","raspberry-pi"],"created_at":"2024-08-03T03:01:55.432Z","updated_at":"2025-04-13T12:50:25.532Z","avatar_url":"https://github.com/jeffbass.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"===========================================================\nyin-yang-ranch: Software \u0026 Raspberry Pis help manage a farm\n===========================================================\n\nYou can watch my PyCon YouTube video about this project here:\n\n**PyCon 2020 Talk:**\n\n**Jeff Bass - Yin Yang Ranch: Building a Distributed Computer\nVision Pipeline using Python, OpenCV and ZMQ**\n\n`PyCon 2020 Talk Video about this project  \u003chttps://youtu.be/76GGZGneJZ4?t=2\u003e`_\n\n`PyCon 2020 Talk Presentation slides  \u003chttps://speakerdeck.com/jeffbass/yin-yang-ranch-building-a-distributed-computer-vision-pipeline-using-python-opencv-and-zmq-17024000-4389-4bae-9e4d-16302d20a5b6\u003e`_\n\nIf you have a question about my PyCon 2020 talk, open an issue!\nFor more about that see `yin-yang-ranch issue 2. \u003chttps://github.com/jeffbass/yin-yang-ranch/issues/2\u003e`_\n\n\nIntroduction\n============\n\nThis project is a collection of Python programs and Raspberry Pi hardware\nprojects to help manage a small urban permaculture farm called **Yin Yang Ranch**.\nThe 2 acre farm is an ongoing science project to build living soil, capture rain\nin barrels, and grow a variety of plants and fruit trees that can feed birds,\nbees, butterflies and people. We are in Southern California about 10 miles from\nthe Malibu coast. Drought and limited rainfall are the toughest climate issues.\nMonitoring and observation are important, so I built a Raspberry Pi Camera system\nto read the water meter and monitor temperatures to optimize irrigation. I can send a\ntext message to the system (\"Susan\") to ask about water usage or temperatures:\n\n.. image:: docs/images/text-messages.png\n\n\nThis repository contains the software and the hardware designs used to build\nour measurement and monitoring systems. **yin-yang-ranch** is a continuously\nevolving project with a lot of hardware hacking and software refactoring.  I\nam open-sourcing everything in case it might be helpful to others.\nMy projects use Raspberry Pi computers, PiCameras, various sensors and related\nelectronics. I control the hardware with Python programs that use computer\nvision, OpenCV, Numpy, pandas, and the PyZMQ messaging library. I use the\nRaspberry Pi GPIO Python module to control lights (e.g., to light the water\nmeter) and irrigation valves.\n\nThe Yin Yang Ranch project is made up of 4 repositories on GitHub:\n\n1. **yin-yang-ranch**: this repository. Overall project design and **librarian** prototype code.\n2. `imageZMQ: Transporting OpenCV images. \u003chttps://github.com/jeffbass/imagezmq\u003e`_\n3. `imagenode: Capture and Send Images and Sensor Data. \u003chttps://github.com/jeffbass/imagenode\u003e`_\n4. `imagehub: Receive and Store Images and Event Logs. \u003chttps://github.com/jeffbass/imagehub\u003e`_\n\n**imageZMQ** moves images taken by Raspberry Pi computers to hub computers\nfor image processing. **imagenode** runs on multiple RPi computers, continuously\ncapturing images, detecting motion, and gathering sensor data (e.g. air and\nsoil temperatures). **imagehub** runs on a Mac or a Linux computer and receives\nimages and event messages from 8-10 Raspberry Pi computers simultaneously.\nI use a variety of computer vision techniques implemented\nin Python. I have programs that can read the water meter. Or tell if that\ncritter moving behind the barn is a coyote or a raccoon.\n\nI also have a website at `yin-yang-ranch.com \u003chttps://www.yin-yang-ranch.com/\u003e`_\nthat will someday display some dashboards on weather, compost temperatures,\nsolar power generation and when the last coyote was spotted. It is just a few\npictures of the ranch for now while I am developing the dashboard software.\n\n.. contents::\n\nThe Overall Design\n==================\n\nThe overall system design is a hub and spoke network with ZMQ messaging between\nRaspberry PiCameras and imagehubs. One image hub can simultaneously receive\nimages from about 10 PiCameras. A librarian program gathers event messages and\nimages from the imagehubs. A communications program uses the event logs to\nanswer queries about images and events, as shown in the SMS text exchange pictured\nabove. By distributing computer vision processing pipelines across Raspberry Pi\ncomputers and more powerful computers like Macs, each computer can do what it\ndoes best. A Raspberry Pi can take pictures with the PiCamera and adjust\ncamera settings, control additional lighting, crop, flip and grayscale images,\nas well as detect motion. A Mac can store and index images from many Raspberry\nPi computers simultaneously. It can perform more complex image processing like\nreading the changing digits of the water meter or using image classification\ntechniques to label a coyote or a raccoon in an image stream. My current setup has\nabout a dozen Raspberry Pis with PiCamera modules and 2 linux laptops with webcams\nattached to a single imagehub.\n\n.. image:: docs/images/CVpipeline.png\n\nThe project contains code repositories for each part of the design shown above:\n\n- **imagenode**: image capture on Raspberry Pi and other computers using PiCameras,\n  webcams and various OpenCV techniques for image rotation, threshholding,\n  dilation, differencing and motion detection. Also sends sensor data, such as\n  temperature and humidity, from sensors attached to the RPi's.\n  See `imagenode: Capture and Send Images and Sensor Data. \u003chttps://github.com/jeffbass/imagenode\u003e`_\n- **imageZMQ**: Python classes that transport OpenCV images from imagenodes to\n  imagehubs. The imageZMQ package is pip installable.\n  See `imagezmq: Transporting OpenCV images. \u003chttps://github.com/jeffbass/imagezmq\u003e`_\n- **imagehub**: receives event messages, images and sensor data from multiple\n  Raspberry Pi and other computers via imagezmq. Stores them to disk files. Note\n  that the **imagenodes** don't store any data to the RPi SD cards, but send all\n  their data to the **imagehub** for storage.\n  See `imagehub: Receiving and saving images and event data from multiple Raspberry Pi's. \u003chttps://github.com/jeffbass/imagehub\u003e`_\n- **librarian**: reads the **imagehub** event logs and stored\n  images to answer questions about them. A prototype of the **librarian** code\n  is contained in this repository. It can answer simple queries like\n  those in the SMS texting example above.\n  See `The Librarian Prototype. \u003cdocs/librarian-prototype.rst\u003e`_\n  Also, for an excellent alternative to my own librarian design, see this\n  `approach. \u003c#an-excellent-alternative-design-for-an-imagehub--librarian-combination\u003e`_\n- **commhub**: provides a very simple natural language interface for answering\n  questions about events and images (is the water running? was a coyote sighted\n  today?). It parses the inbound questions and provides simple answers using data\n  from the **imagehub** event logs. The **commhub** has methods for different\n  channels of communication with end users. The prototype **commhub** code in\n  this repository implements 2 communications channels: 1) SMS texting (using Google\n  Voice and its Gmail interface) and 2) a terminal window CLI text interface.\n- **commagents**: are separate Python programs connecting each communication channel\n  to the **commhub**. For example, an SMS/texting agent (example shown above),\n  is implemented as ``gmail_watcher.py`` in this repository. Future **commagents**\n  such as a Twilio SMS texting agent, an email agent and a webchat agent are\n  being developed.\n- **yin-yang-ranch** (*this GitHub repository*): contains overall project\n  documentation and design. This repository also contains prototype Python\n  programs for the **librarian**, **commhub** and an example **commagent**\n  (in the ``librarian-prototype`` folder). There is also example data from my\n  farm in the ``test-data`` folder. That folder contains **imagehub** logs\n  and captured images from my farm (including images of coyotes, a bobcat, the\n  mail truck and an Amazon delivery ;-)\n\nThis distributed design allows each computer to do what it does best. A\nRaspberry Pi with a PiCamera can watch a water meter for needle motion, then\ntransmit only those images show the water flow changes (from flowing\nto not flowing or vice versa). The logic for motion detection and image\nselection runs in the Raspberry Pi **imagenode**, which only sends relevant images\nto the **imagehub**, saving network bandwidth. The **imagehub** stores the event\nmessages and images from multiple nodes at the same time. The **librarian**\nprogram answers user queries about images and event messages. A more\ncomplete \"which computer does what\" explanation can be found in\n`Distributing tasks among the multiple computers. \u003cdocs/distributed-flow.rst\u003e`_\n\nSoftware Stack for the entire system\n====================================\n\nThe system is written in Python and uses these packages. Higher versions will\nusually work fine, but these specific ones are known to work. See each specific\nrepository above for more software details.\n\n- Python 3.6 through 3.11\n- OpenCV 3.3 and 4.0+\n- Raspian OS Buster, Stretch and Raspbian Jessie using legacy PiCamera\n- Raspberry Pi OS Bookworm and Bullseye using PiCamera2\n- PyZMQ 20.0+\n- imagezmq 1.1.1+\n\nHardware and Electronics\n========================\n\nThe project uses a wide variety of electronics hardware:\n\n- Raspberry Pi computers with both PiCameras and webcams.\n- Mac and Linux laptops (some with webcams as image nodes).\n- Temperature and humidity sensors.\n- Lighting control electronics (e.g., to light the water meter).\n- Motion detection sensors (both PIR and ultrasonic).\n- Infrared lighting arrays (to watch for coyotes and raccoons at night).\n- Irrigation actuators to turn water on and off.\n- Solar panel monitoring hardware with programs to optimize power use and track\n  the daily, monthly and annual sunshine energy reaching the farm. Hours and\n  intensity of sunlight are big factors in photosynthesis, plant growth rates\n  and water requirements.\n\nWater Meter Hardware Example\n----------------------------\nThis is what a water meter looks like:\n\n.. image:: docs/images/water-meter.jpg\n\nThe water meter project uses computer vision to manage water use on the farm.\nI can use computer vision to determine if water is flowing or not, read\nthe gallons used per hour or per day, and save some of the images for analysis.\nThe project also watches for unusual water flow due to leaks or broken irrigation\ncontrols and sends alerts. When the water is flowing, the large analog needle\nspins clockwise. Each full rotation of the needle causes the rightmost\ndigit of the digital meter to advance by one digit. The small \"blue star\" dial\nis a \"leak detector\" that spins even when a very small amount of water is\nflowing (like a dripping faucet).\n\nThe Raspberry Pi sits in a mason jar on top of the water meter cover. The\nPiCamera and the array of LED lights is underneath the water meter cover and\naimed at the water meter face. Here is a picture of the water meter as seen by\nthe PiCamera:\n\n.. image:: docs/images/water-meter-cam-view.jpg\n\nFor more details on the water meter camera electronics and buildout, see\n`Water Meter Camera Hardware Details. \u003cdocs/water-meter-hardware.rst\u003e`_\n\nCoyote Cam and Temperature Sensor Hardware Example\n--------------------------------------------------\nRaspberry Pi nodes around the farm can monitor temperature and detect motion\nof critters wandering about. Here is a log that shows motion detected behind\nthe barn, along with a couple of pictures that were taken when the coyote\nactivated the motion detection in the **imagenode** RPi running in the barn:\n\n.. image:: docs/images/coyote-events.png\n\nHere is what the back of the barn looks like with the infrared \"PiNoir\"\nstyle PiCamera, a temperature sensor and the infrared floodlight that lights the\narea after dark without putting out white light:\n\n.. image:: docs/images/floodlight-cam-sensor.jpg\n\nFor more details on the infrared camera, infrared floodlight and temperature\nsensor, see\n`Critter Infrared Camera and Temperature Sensor Details. \u003cdocs/barn-hardware.rst\u003e`_\n\nDriveway Cam Raspberry Pi Zero Hardware Example\n-----------------------------------------------\nAnother PiCamera **imagenode** watches the driveway and entrance area. It sees\nthe mail truck come and go, and spots an occasional hawk. It uses a Raspberry\nPi Zero W computer and a PiCamera that are encased in a \"fake security camera\"\nhousing that cost about $5:\n\n.. image:: docs/images/camera-housing.jpg\n\nAnd here is what it looks like assembled and mounted in our driveway. You can\nsee the PiCamera behind the housing lens:\n\n.. image:: docs/images/camera-in-place-driveway.jpg\n\nFor more details on the Pi Zero based driveway camera and its enclosure,\nincluding the assembly pictures and some \"action shots\", see\n`Driveway Camera Hardware Example. \u003cdocs/driveway-hardware.rst\u003e`_\n\nResearch and Development Roadmap\n================================\nThe **yin-yang-ranch** projects are in early development and testing.\nPrototypes for all the modules in the design diagram above are working, and the\nearly experiments have provided a lot of data to help with design\nchanges and code refactoring. I have pushed the **imageZMQ**, **imagenode**\nand **imagehub** as separate repositories on GitHub (see links above).\n\nThe **librarian** and its communications programs have prototypes in this\nrepository. They are documented `here. \u003cdocs/librarian-prototype.rst\u003e`_\nThe **librarian** is currently being refactored with a new design, but the\nprototype is what was used to generate the SMS texting example above. It has\nbeen running for about 3 years. It will eventually be pushed to its own\nGitHub repository.\n\nThe `imageZMQ repository \u003chttps://github.com/jeffbass/imagezmq\u003e`_\ncontains test programs that show how images can be sent from multiple Raspberry\nPi computers simultaneously to a hub computer. The **imagenode** and **imagehub**\nprograms are evolutions of the **imageZMQ** test programs\n`timing_send_images.py \u003chttps://github.com/jeffbass/imagezmq/blob/master/tests/timing_send_images.py\u003e`_\nand\n`timing_receive_imnages.py \u003chttps://github.com/jeffbass/imagezmq/blob/master/tests/timing_receive_images.py\u003e`_.\nThe Python code in those two programs is a brief \"pseudo code\" outline for the\ncode that is in the **imagenode** and **imagehub**\nprograms.  Links to the full **imagenode** and **imagehub** repositories are\nabove.\n\nContributing\n============\nThe **yin-yang-ranch** projects are in very early development and testing. I\nwelcome questions and comments.  The easiest way to make a comment or ask a\nquestion about the project is to open an issue. If your issue is specific to\n**imageZMQ**, **imagenode** or **imagehub**, it will be easiest if you open\nan issue in the appropriate project. Issues about the overall project design or\nabout my PyCon 2020 presentation should go into this repository.\n\nAn Excellent Alternative Design for an imagehub \u0026 librarian combination\n=======================================================================\nAn ``imagenode`` \u0026 ``imagehub`` user and code contributor @sbkirby has designed\na completely different approach to building an **imagehub** and **librarian**\ncombination using a broad mix of tools in addition to Python including Node-Red,\nMQTT, MariaDB and OpenCV in Docker containers. He has posted it in this\n`Github repository \u003chttps://github.com/sbkirby/imagehub-librarian\u003e`_.\nI like his approach a lot, although I'm still working on a mostly Python\napproach to my own librarian that is an extension of the prototype librarian in\nthis repository.\n\nAcknowledgments and Thank Yous\n==============================\n- **The Raspberry Pi Foundation** and their remarkable Raspberry Pi tiny single\n  board computers. Even their $10 Pi Zero runs Linux and OpenCV and can do serious\n  computer vision image acquisition and processing.\n  `Raspberry Pi Foundation \u003chttps://www.raspberrypi.org/\u003e`_\n- **Adafruit** an amazing resource for electronics makers with helpful tutorials and\n  electronic components of all kinds. `Adafruit \u003chttps://www.adafruit.com/\u003e`_\n- **ZeroMQ** is a great network messaging library with great documentation\n  at `ZeroMQ.org \u003chttp://zeromq.org/\u003e`_.\n- **OpenCV** and its Python bindings provide great scaffolding for computer\n  vision projects large or small: `OpenCV.org \u003chttps://opencv.org/\u003e`_.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffbass%2Fyin-yang-ranch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffbass%2Fyin-yang-ranch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffbass%2Fyin-yang-ranch/lists"}