{"id":13577815,"url":"https://github.com/filipsPL/cat-localizer","last_synced_at":"2025-04-05T15:31:29.156Z","repository":{"id":44922576,"uuid":"331993468","full_name":"filipsPL/cat-localizer","owner":"filipsPL","description":"Localize your cat at home with BLE beacon, ESP32s, and Machine Learning","archived":false,"fork":false,"pushed_at":"2022-01-18T10:10:52.000Z","size":1013,"stargazers_count":606,"open_issues_count":1,"forks_count":30,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-05T13:01:41.578Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","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/filipsPL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-22T15:59:00.000Z","updated_at":"2025-03-17T16:46:40.000Z","dependencies_parsed_at":"2022-07-17T09:46:13.227Z","dependency_job_id":null,"html_url":"https://github.com/filipsPL/cat-localizer","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/filipsPL%2Fcat-localizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipsPL%2Fcat-localizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipsPL%2Fcat-localizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipsPL%2Fcat-localizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filipsPL","download_url":"https://codeload.github.com/filipsPL/cat-localizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247358736,"owners_count":20926276,"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":[],"created_at":"2024-08-01T15:01:24.566Z","updated_at":"2025-04-05T15:31:29.109Z","avatar_url":"https://github.com/filipsPL.png","language":"Jupyter Notebook","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"readme":"Localize your cat  at home with BLE beacon, ESP32s, and Machine Learning\n=========================\n\n**tl;dr / abstract**. System which can be used for localization the position of a cat in a building using bluetooth low energy (BLE) beacons attached to the object, a set of cheap ESP32 detectors, and Machine Learning models.\n\n\u003c!-- TOC START min:1 max:6 link:true asterisk:false update:true --\u003e\n- [How it works](#how-it-works)\n- [Hardware setup](#hardware-setup)\n- [Software setup](#software-setup)\n  - [BLE beacon](#ble-beacon)\n  - [Detectors](#detectors)\n    - [ESP32](#esp32)\n    - [Raspberry Pi](#raspberry-pi)\n  - [On the server](#on-the-server)\n    - [0. Data source](#0-data-source)\n    - [1. Python environment](#1-python-environment)\n    - [2. Program for cat localization prediction](#2-program-for-cat-localization-prediction)\n- [Training and testing of ML models](#training-and-testing-of-ml-models)\n  - [Data collection](#data-collection)\n  - [Algorithms evaluation and models training](#algorithms-evaluation-and-models-training)\n  - [Conclusions](#conclusions)\n- [Detecting](#detecting)\n- [Tips and tricks](#tips-and-tricks)\n- [Improvements of the accuracy](#improvements-of-the-accuracy)\n- [Further directions](#further-directions)\n- [Acknowledgements](#acknowledgements)\n\u003c!-- TOC END --\u003e\n\n\n# How it works\n\nThis is an overwiev of a pipeline for creating an inhouse cat locator. Actually, it can be applied to any animal (including humans) or object, and any building. The system works as follows:\n\n![](obrazki/README-8d01da21.png)\n\n- The cat with a small BLE beacon, is emiting BLE signals\n- BLE signal is detected by ESP32s located here and there; they are measuring he signal strength of the BLE beacon.\n- Each ESP32 sends data to the server (database)\n- The python program is fetching the last measurements from all ESP32 detectors (i.e., signal strenght values)\n- Using trained machine learning models it predicts the location of the cat\n\n:bulb: The challenge here is to use a number of detectors which is significantly lower than the number of rooms and make ML do the rest.\n\n:bulb: This is *not a ready-to-use* set of programs. As each situation is different (i.e, hardware setup, house size, number of rooms etc), please treat this repo as a framework to build and customize your own system.\n\n# Hardware setup\n\n- **Moving object to track.** A cat. A dog is also fine. Be careful with fishes. Can be more than one. I used two cats. 💰 ~ 0 $\n- **BLE transmitters**. [A BLE beacon](https://en.wikipedia.org/wiki/Bluetooth_low_energy_beacon). Anything will be good. I used [NotiOne](https://notione.com/) buttons, they work well and has an additional functionality (not used here). But something cheaper will work too. 💰 n x 10-20 $\n- **BLE detectors**. I used four ESP32. I guess 4-6 for moderate house/flat should be enough. One can use also modern raspberry pi with BLE. 💰 n x 4 $\n- **Data processing**. A server/computer. I worked with amd64 Debian, but any Raspberry Pi should be also good. Can be remote. Can be done in a microcontroller (see: [further directions](#further-directions))\n- WiFi Connectivity (ESPs to the server)\n\nOptional:\n- LCD display showing the current location of the cat. I'm using TTGO1\n\n# Software setup\n\n## BLE beacon\n\nNothing to configure nor code here :-)\n\n## Detectors\n###  ESP32\n\nI provide a simple C/Arduino code for the detector. Of course it can do much more (my ESPs also measure temperature, humidity and other parameters):\n\n- [simple C/Arduino program for BLE scanning and talking with a server](2-ESP32/esp32-ds18b20-living_room.ino)\n\nMany things can be tuned and optimized (eg array of MAC addreses instead of single variables, reading MAC addresses from the server etc).\n\n### Raspberry Pi\n\n(this solution was not thoroughly tested!)\n\nRaspberry Pi with a BLE capability can be included in the set of detectors. The commands here are:\n\n```sh\nbtmon \u0026\nhcitool lescan --duplicates | grep MAC\n```\n\nand next sending to the database.\n\n## On the server\n\n### 0. Data source\n\nWe need a server with a database. I use influx, but any will be good (MySQL or even text files!)\n\n### 1. Python environment\n\nI used Python 3.8.\n- libraries: scikit and pandas, and whatever is needed to fetch data from the database\n- please see a sample conda environment file to see what is my setup\n- remember that the trained ML models must be next used in the same environment (the same scikit and numpy version!); this can be guaranteed by using the dedicated cond environment\n\nSample conda environment can be impotred by issuing (this is a single time procedure):\n```\nconda env create -f cat-localizer.yml\n```\n\nand activated by:\n\n```\nconda activate cat-localizer\n```\n\nTraining of ML models can be done on any computer (eg laptop) and next models transfered to the main server. Remember to keep the same modules version (use conda environment). See the next section on model training.\n\n### 2. Program for cat localization prediction\n\nWhen models are trained and ready (see the next section), we use python program to fetch last BLE signal strength data and - basing on this - predict localization of the cat. Please see the section [Detecting](#detecting) for more info and code samples.\n\n\n# Training and testing of ML models\n\n## Data collection\n\nHere we collect data for training ML algorithms. This means we have to collect signal strength data from all sensors WITH associated localization of the beacon. I.e, lets assume we have four ESP32 sensors, we need to create table like this one:\n\n|measurement id|time        |target |esp32-attic|esp32-room_k|esp32-office|esp32-doors|\n|------|-----------------|-------|-----------|------------|------------|-----------|\n|0     |2021-01-03 15:32 |office |-71.0      |-110.0      |-71.5       |-83.0      |\n|1     |2021-01-03 15:33 |office |-73.0      |-110.0      |-82.5       |-82.5      |\n|2     |2021-01-03 15:34 |office |-81.0      |-110.0      |-80.0       |-87.5      |\n|3     |2021-01-03 15:35 |office |-75.0      |-110.0      |-86.5       |-86.5      |\n|4     |2021-01-03 15:36 |office |-72.5      |-110.0      |-78.5       |-81.0      |\n|...   |...              |...    |...        |...         |...         |...        |\n|236   |2021-01-03 21:56 |room_k |-100.5     |-67.5       |-110.0      |-91.5      |\n|237   |2021-01-03 21:57 |room_k |-86.0      |-60.0       |-110.0      |-91.5      |\n|238   |2021-01-03 21:58 |room_k |-88.5      |-93.5       |-110.0      |-91.5      |\n|239   |2021-01-03 21:59 |room_k |-86.0      |-75.0       |-110.0      |-91.5      |\n|240   |2021-01-03 22:00 |room_k |-87.0      |-72.0       |-110.0      |-84.5      |\n\nwhere each row (measurement) represent RSSI values read from beacon at a given location **at the same time**. Please see [jupyter notebook](4-ML/1-process_data.ipynb) for the data preprocessing.\n\nWhen this table is ready, we can go further and train ML models.\n\nThe number of data points (i.e, different locations of BLE beacon) for each room is variable and depends on the room size. In my case it was like here:\n\n```\nroom           no of measurements\nbathroom_d      11\nbathroom_g      30\nliving_room    101\noffice          38\nroom_k          32\nroom_m          28\n```\n\nRemember to sample space available for your cats, so not only floors, but also tables, wardrobes, or chandelier etc ;-)\n\n## Algorithms evaluation and models training\n\nNow we will probe several preprocessing algorithms together with several  Machine Learning methods. We don't know which one will be the best in our case, so we will probe them all in a cross-validation experiment.\n\nPlease see [jupyter notebook](4-ML/1-process_data.ipynb) for the exact pipeline.\n\nThe final models will be build with at 75% of the dataset (training), while 25% will seve as a testing dataset.\n\n## Conclusions\n\nThe ML algos cv results is shown here (balanced accuracy values are shown):\n\n![](obrazki/README-a7db4c56.png)\n\nwe can see that in our case, the MLP Classifier with Min-Max Scaler gives the best results.\n\nLet's see if we can go any further with some features engeneering:\n\n![](obrazki/README-ef170c08.png)\n\nThe nswer is no. The best accuracy here is the same as an initial setup (0.83), so we will stay with the MLP Classifier with Min-Max Scaler.\n\nThe final models build with MLP Classifier with Min-Max Scaler gives the balanced accuracy equal 0.88. Very good! If we look at the confusion matrix:\n\n![](obrazki/README-456edd00.png)\n\nwe will see that (believe me or not) all miss-labelled predictions are for locations which are close to each other (eg. room_m is close in space to the office etc.). So this makes a perfect sense.\n\n\n# Detecting\n\nFor the detection you can use the code snippet in the section 6 of [jupyter notebook](4-ML/1-process_data.ipynb#Reuse-saved-models-for-new-predictions) or the code of the [simple program](3-server/localize-cat.py). The program uses numpy array as a data source, but it can be read from the file or fetched from the database.\n\n# Tips and tricks\n- gathering data for training ML. I used 1-minutes interval of collecting data. This gave me time to change the position of beacons in the room. Measurements were automatically stored in the database (influx). I noted the time span of collectiong data in a given room and then fetched data from db for this time period, assigned a room label, and saved in a csv file.\n- for collection of data for a flat surfaces (floors) you can use devices such as roomba with beacons attached at the top of it. Works fine!\n\n# Improvements of the accuracy\n\n- Optimization of the position of ESP32 detectors, to cover whole space and give unique signal patterns for each rooms\n- Optimization of ML algorithms and parameters\n- Increasing number of ESP32 detectors (but this is not a chalenge :))\n- (?) Take into account the battery level of the BLE beacon, as this could have impact on the transmitting power. I'm not sure.\n\n# Further directions\n\n- after some time of collecting the localization data for objects, we may create another ML model for predicting the localization of object in time (i.e., if it is Monday morning, the cat is near the fridge, if it is Saturday afternoon, the cat is sleeping in the bathroom, etc). This could involve another variables, like room temperature, humidity etc.\n- move the prediction step to (another) microcontroller (ESP32, ESP8266) with such (cool!) project: https://github.com/eloquentarduino/micromlgen (no need to have a dedicated server for predictions)\n\n# Acknowledgements\n\n- wikimedia commons and openclipart library for cool graphics (especially the cat!)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfilipsPL%2Fcat-localizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FfilipsPL%2Fcat-localizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfilipsPL%2Fcat-localizer/lists"}