{"id":24576466,"url":"https://github.com/k0rventen/smart-mailbox","last_synced_at":"2026-04-24T20:31:17.982Z","repository":{"id":143187979,"uuid":"182761040","full_name":"k0rventen/smart-mailbox","owner":"k0rventen","description":"a connected, twitter-enabled mailbox that tweets you when there is mail","archived":false,"fork":false,"pushed_at":"2019-04-22T11:05:17.000Z","size":3269,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-28T15:43:10.724Z","etag":null,"topics":["arduino","bluetooth","home-automation","mailbox","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k0rventen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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,"zenodo":null}},"created_at":"2019-04-22T10:58:12.000Z","updated_at":"2019-05-18T11:28:23.000Z","dependencies_parsed_at":"2023-05-03T10:01:11.514Z","dependency_job_id":null,"html_url":"https://github.com/k0rventen/smart-mailbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/k0rventen/smart-mailbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k0rventen%2Fsmart-mailbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k0rventen%2Fsmart-mailbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k0rventen%2Fsmart-mailbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k0rventen%2Fsmart-mailbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k0rventen","download_url":"https://codeload.github.com/k0rventen/smart-mailbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k0rventen%2Fsmart-mailbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32239441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["arduino","bluetooth","home-automation","mailbox","python"],"created_at":"2025-01-23T22:39:13.314Z","updated_at":"2026-04-24T20:31:17.977Z","avatar_url":"https://github.com/k0rventen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A smart, connected mailbox\n\n**Why going every day in front of the mailbox, when you could have a smart mailbox that notifies you when there's mail ?**\n\n![](demo.gif)\n\n## The concept\n\nThe idea is to be able to know if there is something in the mailbox, without complex or expensive materials, nor taking too much space. \n\nThe system is as follows :\n- A LED is located on the inside top of the mailbox, facing down. \n- On the floor of the mailbox is a set of photosensors facing up.\n\nAll the photosensors (aka photoresistors) are connected to an Arduino, and give a voltage response based on the light they receive. Using the Arduino's on-board analog to digital converter, we can map this response, from 0 (no light) to 1024 (peak brightness of the sensor).\n\nTo check if there is mail, we light up the LED on the top then check all the sensors. If the sensors responses are above 0, none of the sensors are blocked.\n\nBut if one of them replies 0, it means the sensor is \"blocked\" from the LED's light, by a letter or package..\n\nTo communicate, the Arduino uses a bluetooth connexion, via a HC-05 module. On the other end, you can use any device capable of initiating a Bluetooth connection (like a raspberry pi).\n\n\n## Hardware\n\n- 1 White 5V LED\n- 6 photosensors\n- 6 470 Ohm resistors\n- 1 Arduino (Uno or even Nano for size's sake)\n- 1 HC-05 bluetooth module\n- some cables\n\nBelow is a schematic of the embedded part : \n\n![](./mail_detection_schem.png)\n\nEvery photosensor is connected to an analog pin on the arduino.\n\n## Embedded part\n\nThe embedded code relies on the `SoftwareSerial` [library](https://www.arduino.cc/en/Reference/SoftwareSerial) to communicate with the bluetooth dongle.\n\nOnce installed, just compile and upload the `.ino` file on the arduino.\n\n## Server\n\nTo interface the embedded system, a python script that runs on a nearby device (like a Raspberry Pi) connects to the arduino using its Bluetooth address, and retrieve the status of each sensor. \n\nTo be able to connect to the arduino via Bluetooth, you will need to pair it before, here using bluetoothctl: \n\n```bash\nbluetoothctl\n\u003e power on\n\u003e default-agent\n\u003e scan on\n\u003e trust XX:XX (MAC addr of the HC:05)\n\u003e pair XX:XX (MAC addr of the HC:05)\n\u003e Enter PIN : 1234 (The actual pin code is 1234)\n\u003e quit\n```\n\nThe MAC address of the dongle must be added in the python script :\n\n```python\narduino = \"Your Arduino MAC address here\"\n```\n\nYou can customize the script to do whatever you desire when there is mail : \n\n```python\nif results.count(1) is 5:\n        # There is mail, do stuff !\n\n        # Uncomment for twitter integration\n        # twitter_notify()\n        pass\n    else:\n        # No mail\n        pass\n```\n\nTo have the milbox fetched automatically, you can add a new entry in cron, like so :\n\n`*/10 * * * * python path/to/mailbox_fetch.py`\n\n## Twitter integration\n\nIf you want your mailbox to be twitter-enabled, you will need a few things : \n\n- a separate twitter account for the mailbox, with dev mode enabled and an app setup (PITA to setup, follow [this guide](https://python-twitter.readthedocs.io/en/latest/getting_started.html))\n- the id of your own twitter account, which you can get from [here](https://tweeterid.com)\n- the package, via `pip install python-twitter`\n\nIn the python script, just setup the following variables, according to your twitter Dev app keys and tokens : \n\n```python\ntwitter_id=\"\u003cYour twitter ID\u003e\"\napi = twitter.Api(consumer_key=\"\",\n                  consumer_secret=\"\",\n                  access_token_key=\"\",\n                  access_token_secret=\"\")\n```\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0rventen%2Fsmart-mailbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk0rventen%2Fsmart-mailbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0rventen%2Fsmart-mailbox/lists"}