{"id":13893740,"url":"https://github.com/JChristensen/CurrentTransformer","last_synced_at":"2025-07-17T08:30:41.986Z","repository":{"id":140628845,"uuid":"143170126","full_name":"JChristensen/CurrentTransformer","owner":"JChristensen","description":"Arduino Current Transformer Library","archived":false,"fork":false,"pushed_at":"2020-02-16T20:48:07.000Z","size":72,"stargazers_count":16,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-24T22:32:13.592Z","etag":null,"topics":["alternating-current","arduino","arduino-library","current","rms","sensor","transformer"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/JChristensen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-08-01T14:51:12.000Z","updated_at":"2024-09-10T08:15:53.000Z","dependencies_parsed_at":"2024-01-16T21:24:50.834Z","dependency_job_id":"644ee984-1faa-47b5-8276-80ccfbf392e6","html_url":"https://github.com/JChristensen/CurrentTransformer","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/JChristensen/CurrentTransformer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FCurrentTransformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FCurrentTransformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FCurrentTransformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FCurrentTransformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JChristensen","download_url":"https://codeload.github.com/JChristensen/CurrentTransformer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JChristensen%2FCurrentTransformer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265585272,"owners_count":23792712,"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":["alternating-current","arduino","arduino-library","current","rms","sensor","transformer"],"created_at":"2024-08-06T18:01:15.720Z","updated_at":"2025-07-17T08:30:41.670Z","avatar_url":"https://github.com/JChristensen.png","language":"C++","readme":"# Arduino CurrentTransformer Library\nhttps://github.com/JChristensen/CurrentTransformer  \nREADME file  \n\n## License\nArduino CurrentTransformer Library Copyright (C) 2018 Jack Christensen GNU GPL v3.0\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see \u003chttps://www.gnu.org/licenses/gpl.html\u003e\n\n## Introduction\nThe CurrentTransformer library measures RMS current values in a 50/60Hz AC circuit using [current transformers](https://en.wikipedia.org/wiki/Current_transformer). Each read causes the analog-to-digital converter (ADC) to measure a single AC cycle. The data gathered is processed using the [standard RMS calculation](https://en.wikipedia.org/wiki/Root_mean_square#Definition) to give the result in amperes.\n\nThe library contains two classes. `CT_Sensor` is used to define one or more current transformers. `CT_Control` does the actual measurement when `CT_Control::read()` is called. Each call to `read()` can read either one or two current transformers in a single AC cycle.\n\nSince each call to `read()` measures only a single cycle, it may be desirable, depending on the application and the nature of the electrical load, to make several calls, perhaps averaging the results, removing transients, etc. Each call to `read()` only takes about as long as one AC cycle, so there is not a lot of overhead or delay in taking several measurements.\n\nBecause measuring AC causes the current transformer to output positive and negative currents, a DC bias must be applied to ensure that below-ground voltages are not applied to the microcontroller's ADC input. It is also necessary to ensure that peak voltages do not exceed the microcontroller's supply voltage (Vcc). Do the math to ensure that your circuit operates within safe limits; also see the example below.\n\nThis library is specific to the AVR microcontroller architecture and will not work on others. Only ATmega328/P, ATmega1280 and ATmega2560 are supported. Timer/Counter1 is used to trigger the ADC conversions and so is not available for other purposes.\n\n## Example Design Calculations\n\nThe TA17L-03 current transformer is rated at 10A maximum and has a 1000:1 turns ratio. A 200Ω burden resistor is recommended. A 10A RMS current in the primary will generate a 10mA current in the secondary and therefore 2V across the burden resistor. However the peak voltage will then be √2 * 2V = ±2.8V (assuming a sine wave) which exceeds the 2.5V DC bias provided by the circuit below. Therefore the measured current should be limited to about 8.5A RMS (giving ±2.4V P-P) or perhaps a smaller burden resistor could be used if larger currents need to be measured.\n\n## Typical Circuit\n![](https://raw.githubusercontent.com/JChristensen/CurrentTransformer/master/extras/typical-circuit.png)\n\n## Enumeration\n### ctFreq_t\n##### Description\nOperating frequency for the current transformer.\n##### Values\n- CT_FREQ_50HZ\n- CT_FREQ_60HZ\n\n## Constructors\n\n### CT_Sensor(uint8_t channel, float ratio, float burden)\n### CT_Sensor(uint8_t channel, float amps, float volts)\n##### Description \nDefines a CT_Sensor object. One or more CT_Sensor objects can be defined as needed.  \nThe first form is for current transformers with a user-supplied burden resistor. In this case, the turns ratio and the burden resistor value are given.  \nThe second form is for current transformers with a built-in burden resistor. These are often specified as the output voltage corresponding to the maximum input current, e.g. 20A/1V.\n##### Syntax\n```c++\nCT_Sensor myCT(channel, ratio, burden);\n/* or */\nCT_Sensor myCT(channel, amps, volts);\n```\n##### Parameters\n**channel:** ADC channel number that the current transformer is connected to. (Arduino pin numbers can also be used, e.g. A0-A5). *(uint8_t)*  \n**ratio:** Secondary-to-primary turns ratio for the current transformer. *(float)*  \n**burden:** Current transformer burden resistor value in ohms. *(float)*  \n**amps:** Maximum rated current for the current transformer. *(float)*  \n**volts:** Voltage output corresponding to the maximum current input. *(float)*\n##### Example\n```c++\nCT_Sensor mySensor(0, 1000, 200);   // 1000:1 turns ratio, 200Ω burden resistor\n/* or */\nCT_Sensor mySensor(0, 20, 1);       // 1 volt output at 20 amps (built-in burden resistor)\n```\n\n### CT_Control(ctFreq_t freq)\n##### Description\nDefines a CT_Control object. Only one CT_Control object needs to be defined.\n##### Syntax\n`CT_Control ctCtrl(freq);`\n##### Optional parameter\n**freq:** AC line frequency, either `CT_FREQ_50HZ` or `CT_FREQ_60HZ`. Defaults to `CT_FREQ_60HZ` if not given. *(ctFreq_t)*  \n##### Example\n```c++\nCT_Control myCtrl(CT_FREQ_50HZ);\n```\n\n## Library Functions\n\n### float CT_Sensor::amps()\n##### Description\nReturns the current value in RMS amperes read by the last call to `CT_Control::read()`.\n##### Syntax\n`mySensor.amps();`\n##### Parameters\nNone.\n##### Returns\nRMS current value in amperes *(float)*\n##### Example\n```c++\nfloat rmsCurrent;\nrmsCurrent = mySensor.amps();\n\n```\n\n### float CT_Control::begin()\n##### Description\nInitializes the AVR timer and ADC. (Timer/Counter1 is used to trigger the ADC conversions and so is not available for other purposes.)\n##### Syntax\n`myCtrl.begin();`\n##### Parameters\nNone.\n##### Returns\nMicrocontroller supply voltage in volts. *(float)*  \n##### Example\n```c++\nfloat vcc = myCtrl.begin();\n```\n\n### void CT_Control::end()\n##### Description\nResets the AVR timer and ADC to default configuration.\n##### Syntax\n`myCtrl.end();`\n##### Parameters\nNone.\n##### Returns\nNone.  \n##### Example\n```c++\nmyCtrl.end();\n```\n\n### void CT_Control::read(CT_Sensor *sensor1)\n### void CT_Control::read(CT_Sensor *sensor1, CT_Sensor *sensor2)\n##### Description\nGiven one or two CT_Sensor object addresses, measures the RMS current value for one AC cycle. After calling `read()`, access the measured RMS current value(s) via the `CT_Sensor::amps()` function.\n##### Syntax\n`myCtrl.read(\u0026mySensor);`\n##### Parameters\nNone.\n##### Returns\nNone.\n##### Example\n```c++\nCT_Sensor mySensor(0, 1000, 200);\nCT_Control myCtrl(CT_FREQ_50HZ);\nmyCtrl.read(\u0026mySensor);\nfloat rmsCurrent = myCT.read();\n\n```\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJChristensen%2FCurrentTransformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJChristensen%2FCurrentTransformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJChristensen%2FCurrentTransformer/lists"}