{"id":20472148,"url":"https://github.com/f321x/metalguard-esp32","last_synced_at":"2025-07-01T14:06:35.395Z","repository":{"id":194627406,"uuid":"690694897","full_name":"f321x/metalguard-esp32","owner":"f321x","description":"Documentation and code to utilize the touch pins of an esp32 to safeguard a piece of metal.","archived":false,"fork":false,"pushed_at":"2023-09-15T18:33:19.000Z","size":18,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-05T13:49:36.269Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/f321x.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-12T17:26:19.000Z","updated_at":"2024-05-19T20:48:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"4af92e5e-f421-4782-8fd5-7e23d7f49010","html_url":"https://github.com/f321x/metalguard-esp32","commit_stats":null,"previous_names":["f321x/metalguard-esp32"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/f321x/metalguard-esp32","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f321x%2Fmetalguard-esp32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f321x%2Fmetalguard-esp32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f321x%2Fmetalguard-esp32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f321x%2Fmetalguard-esp32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f321x","download_url":"https://codeload.github.com/f321x/metalguard-esp32/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f321x%2Fmetalguard-esp32/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262978585,"owners_count":23394009,"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-11-15T14:18:47.754Z","updated_at":"2025-07-01T14:06:35.342Z","avatar_url":"https://github.com/f321x.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metalguard-esp32\nThe touch pins of an esp32 microcontroller can be used to send a notification when a connected metal part is being touched with finger.\nIn combination with the deep sleep feature of an esp32 and a lithium battery this can be used to monitor a piece of metal for years with minimum attention.\n\nThis repository is intended to provide all the necessary code and documentation to set up an esp32 to monitor a piece of metal by an enthusiastic beginner (techie).\n\nTime needed: one Sunday evening\n\n# Chapters\n1. [Introduction](#metalguard-esp32)  \n2. [Hardware](#2-hardware)    \n3. [Preparing the necessary software](#3-preparing-the-necesary-software)\n4. [Create a Telegram Bot](#4-creating-a-telegram-bot)\n5. [Configuring the firmware](#5-configuring-the-firmware)\n6. [Flashing the esp32](#6-flashing-the-esp32)    \n7. [Beheading the esp32](#7-beheading-the-esp32)\n8. [Putting everything together](#8-putting-everything-together)\n9. [Support](#9-support)\n10. [Donation](#9-donation)\n\n## 2. Hardware\n- ESP-WROOM-32 microcontroller dev board, i used a \"ESP32 NodeMCU\" (~7€), recommended to buy on serious plattform to avoid malfunctioning fakes\n- male-male jump wires (~2€ on aliexpress)\n- CR123A Lithium batterie(s)\n- case for CR123 batteries (either Aliexpress or 3D printed)\n- fine soldering iron + solder\n- silicone or hot glue \n\n## 3. Preparing the necesary software\nTo flash the firmware on the ESP32 you will need a computer with the right software.\nIn this documentation i show the usage of Visual Studio Code with the PlattformIO.\n\n1. Install Visual Studio Code (https://code.visualstudio.com/)\n2. Install the PlattformIO Extension (https://platformio.org/install/ide?install=vscode)\n3. Watch this 10min PlattformIO introduction (https://www.youtube.com/watch?v=PYSy_PLjytQ)\n4. **If** you are running **GNU/Linux** you will probably need to set up udev rules for the esp32 to be able to communicate with the computer (https://docs.platformio.org/en/stable//core/installation/udev-rules.html)\n5. Download/Clone this repository\n6. In the PlattformIO main screen, click \"Open Project\", open this project in the repository\n\n## 4. Creating a Telegram bot\nIn my setup i used Telegram to get quick and reliable notifications on my smartphone. You could also implement E-Mail, Nostr, ham radio or any other kinds of communication.\n\nIf you want to follow this guide you will need to set up a Telegram bot to continue.\nYou will need the API token of the bot and the chat ID of your Telegram account.\n\n**How to create the Telegram bot with Botfather and get the api key:** https://sendpulse.com/knowledge-base/chatbot/telegram/create-telegram-chatbot\n\n**How to get your Chat ID:** https://www.alphr.com/find-chat-id-telegram/\n  -\u003e TLDR: search for some \"Chat ID\" bot in the Telegram app, contact it and you will get your chat ID if you messaged a working bot :D\n\nNow you should have 2 strings like the following examples:\n\nBot API token: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\n\nChat ID: 210987654\n\n## 5. Configuring the Firmware:\nIn the folder **src** open the file **main.cpp** (in VS Code)\n\nHere you can see the following part in line 4-12:\n\n~~~\n#define WIFI_SSID \"YOUR WIFI NAME\"\n#define WIFI_PASS \"YOUR WIFI PASSWORD\"\n#define BOT_TOKEN \"YOUR TELEGRAM BOT TOKEN\"\n#define CHAT_ID \"YOUR TELEGRAM CHAT ID\"\n#define Threshold 50  // how sensitive the touch detection should be, higher == more sensitive\n\nunsigned long long sleep_duration = 2592000000000;    // 30 days\n// unsigned long long sleep_duration = 3600000008;     // 1 hour\n// unsigned long long sleep_duration = 86400000192; // ~24 hours\n~~~\n\nSet your **wifi** and **telegram** credentials in the code. \n\nSet the **touch sensibility** with **Threshold**, higher is more sensitive. 50 is already pretty sensitive.\n\n**sleep_duration** is the time interval in µs in which the esp will send you a test notification as status to notice if the battery is empty. (only one has to be active the others are commented out with //)\n\n\n## 6. Flashing the esp32\nTo flash the configured firmware to the esp32:\n1. Connect the esp32 to your computer over usb\n2. Go to the PlattformIO home screen (little house in the bottom bar)\n3. Open the **Devices** register and copy the address of your esp32\n4. Open the file plattformio.ini in your project folder and add:\n~~~\nupload_port = /your/device/path (for example /dev/ttyUSB0)\n~~~\n5. Now you can click on the arrow in the bottom bar to upload the firmware to the esp32. It will be compiled and uploaded automatically. In case of errors look them up on Google (or Kagi).\n\nThe esp is now ready and you should be able to test it.\nConnect it to a power supply and touch the **GPIO PIN 15 (T3)**, or connect a cable to it and touch the cable.\nYou should get a Telegram message in some seconds if everything is configured correctly and the esp32 is in range of the configured wifi network.\n\n## 7. Beheading the esp32\nSupplying the esp32 over the dev board would increase the energy usage, also the esp32 is easier to hide if not mounted on a dev board.\nWarning: you won't be able to easily flash the esp32 again after **unsoldering** it from the dev board and will only be able to supply it with **3.3V** as it has no voltage converter integrated.\n\n![esp32bild](https://github.com/f321x/metalguard-esp32/assets/51097237/35158725-3b9b-4dfb-923f-7a2a386c9d25)\n\nTo desolder the esp32 from its dev board i used a hot air gun from the back of the board and pulled the esp chip from the board after the solder got loose.\n\n## 8. Putting everything together\n1. Solder CR123 battery holder to 3.3V pin (VIN) + EN Pin and ground pin (GND) of the esp32.\n2. Solder cable to touch pin (GPIO 15, also called TOUCH3)\n3. Attach other end of the touch cable to your valuable metal part. If you want to monitor a non conductive part you can also wrap it in aluminum foil and attach the touch cable to the aluminum foil.\n4. Insert the CR123 battery in the battery holder.\n5. Test your setup if everything is functioning as inteded.\n6. Sleep well with your new safety system :D\n\n![ESP32-wroom-32-pinout-mischianti-high-resolution](https://github.com/f321x/metalguard-esp32/assets/51097237/785182e8-483d-45da-a264-765fb481c3a8)\n\n## 9. Support\nIf you need help assembling this or encountered any problems you can connect with others in this Telegram group chat: https://t.me/+T_DB7qpHodI4ZDNi\n\n## 9. Donation\nIn case this guide and the code is useful for you or lets you sleep better feel free to send me some satoshis to the following lightning address: x@lnaddress.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff321x%2Fmetalguard-esp32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff321x%2Fmetalguard-esp32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff321x%2Fmetalguard-esp32/lists"}