{"id":14963462,"url":"https://github.com/bertrik/gridfrequency","last_synced_at":"2025-10-25T02:30:46.016Z","repository":{"id":249419728,"uuid":"831055521","full_name":"bertrik/GridFrequency","owner":"bertrik","description":"Arduino project to measure mains/grid frequency and publish it as SSE and MQTT streams","archived":false,"fork":false,"pushed_at":"2025-01-28T18:09:15.000Z","size":239,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-28T19:23:59.920Z","etag":null,"topics":["arduino","frequency","grid","mains","mqtt","sse"],"latest_commit_sha":null,"homepage":"","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/bertrik.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":"2024-07-19T14:56:12.000Z","updated_at":"2025-01-28T18:08:57.000Z","dependencies_parsed_at":"2025-01-11T20:23:09.907Z","dependency_job_id":"ffbf470a-758d-498b-aeff-5531a96bb4e6","html_url":"https://github.com/bertrik/GridFrequency","commit_stats":{"total_commits":32,"total_committers":1,"mean_commits":32.0,"dds":0.0,"last_synced_commit":"20c5ab0511f70b63bfa492985c3b8b9563550abc"},"previous_names":["bertrik/gridfrequency"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertrik%2FGridFrequency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertrik%2FGridFrequency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertrik%2FGridFrequency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertrik%2FGridFrequency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bertrik","download_url":"https://codeload.github.com/bertrik/GridFrequency/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238065130,"owners_count":19410587,"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":["arduino","frequency","grid","mains","mqtt","sse"],"created_at":"2024-09-24T13:31:32.324Z","updated_at":"2025-10-25T02:30:45.677Z","avatar_url":"https://github.com/bertrik.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GridFrequency\nArduino project to measure mains/grid frequency and publish it as SSE and MQTT streams with display on an internal web server\n\n## Introduction\nThis Arduino software allows you to measure the mains grid frequency (nominally 50 Hz) to high resolution (1 mHz)\nand display the frequency on a web page served from an internal web server.\n\n![example](images/example.png)\n\n### Future\nPlans for the future are:\n* add support for sending measurements over MQTT\n* display instantaneous phase measurement\n* display not just instantaneous frequency but also little graphs over time\n\n## Design\nThis project is the result of various iterations of trying to build a simple device to measure mains frequency.\nSo far this is the simplest hardware design, coupled with the most accurate software algorithm.\n\nThe algorithm samples a floating ADC input during 1 second, picking up the ambient mains 'hum'.\nWhile sampling, the measured waveform is correlated with a 'perfect' reference 50 Hz quadrature waveform.\nThis gives an I and Q value from which the relative phase between the measured waveform and the reference waveform can be determined.\nSmall frequency deviations in the actual mains waveform cause this phase to shift over time.\nFrom this shift, the instantaneous frequency of the measured waveform is derived each second.\n\nThe measured frequency values are published on /events as server-sent events (SSE).\nThe internal web server serves a web page with javascript that connects an event source to this SSE stream.\nThe instantaneous value is visualized as a gauge using [canvas-gauges](https://canvas-gauges.com) by Mykhailo Stadnyk.\n\n## Hardware\nThe hardware consists of a Luatos ESP32-C3 board:\nhttps://wiki.luatos.org/chips/esp32c3/board.html\n\nNo connection to the mains is required. The mains signal is picked up from the ambient electric field of mains \"hum\" on an unconnected ADC input of the ESP chip.\n\nThis board was chosen because it is inexpensive, has a relatively stable and accurate clock crystal and has ADC inputs that are 'floating'.\n\n## Software\n\n### Building\nThis project is built using platformio.\n\nOne time steps for Debian:\n* Use apt to install python3 and python3-pip:\n```\nsudo apt update\nsudo apt install python3 python3-pip\n```\n* Clone this archive using git:\n```\ngit clone https://github.com/bertrik/GridFrequency\ncd GridFrequency\n```\n* Create a python virtual environment\n```\npython3 -m venv .venv\n```\n* Activate the python virtual environment and install platformio:\n```\nsource .venv/bin/activate\npip install platformio\n```\n\nTo build the program:\n* Activate the python virtual environment, if you haven't already in the steps above:\n```\nsource .venv/bin/activate\n```\n* Compile the program:\n```\npio run\n```\nPlatformio will install the required build tools and libraries automatically (and cache them for later use).\nWhen finished, you should see a message indicating a successful build and some info about RAM and flash usage.\n\n### Flashing\nTo flash the board:\n* Connect the board using a USB-C cable to your computer\n* You might need to add yourself to the 'dialout' group, then log in again:\n\u003e ...\n* Upload the program plus its web server files:\n```\npio run -t upload\n```\n\n### Running\nWhen running for the first time, no WiFi connection has been set up. The sofware will create its own WiFi access point.\nConnect to this (no password) and browse to http://192.168.4.1 to choose a network to connect to,\nenter the WiFi password and press save. The board should reboot and automatically connect to your WiFi from now on.\n\nWhen it has successfully connected to the WiFi network, the LED starts flashing slowy, 1 second on, 1 second off.\n\nYou can view frequency measurements by browsing to http://gridfrequency.local\n\n#### MQTT configuration\nMeasurements can also be sent to an MQTT server.\nTo configure MQTT, browse to http://gridfrequency.local/config\n\n![example](images/mqtt-config.png)\n\nEntering a broker host enables sending to MQTT, leaving it empty disables it.\nUser name and password can be left empty, the topic is mandatory.\nWith the 'append unit' option, measurements are published as '50.000 Hz', otherwise just a number like '50.000'.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertrik%2Fgridfrequency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbertrik%2Fgridfrequency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertrik%2Fgridfrequency/lists"}