{"id":25242666,"url":"https://github.com/ageagainstthemachine/ze15-co-circuitpython","last_synced_at":"2025-04-05T20:36:27.647Z","repository":{"id":277005053,"uuid":"923941855","full_name":"ageagainstthemachine/ZE15-CO-CircuitPython","owner":"ageagainstthemachine","description":"A CircuitPython library for the ZE15-CO sensor by Winsen.","archived":false,"fork":false,"pushed_at":"2025-02-13T05:12:51.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T20:36:18.959Z","etag":null,"topics":["carbon-monoxide","carbon-monoxide-gas-sensor","carbon-monoxide-sensor","circuitpython","circuitpython-library","circuitpython-project","winsen","ze15-co"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ageagainstthemachine.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":"2025-01-29T05:32:44.000Z","updated_at":"2025-02-13T05:12:54.000Z","dependencies_parsed_at":"2025-02-11T16:38:40.149Z","dependency_job_id":null,"html_url":"https://github.com/ageagainstthemachine/ZE15-CO-CircuitPython","commit_stats":null,"previous_names":["ageagainstthemachine/ze15-co-circuitpython"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageagainstthemachine%2FZE15-CO-CircuitPython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageagainstthemachine%2FZE15-CO-CircuitPython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageagainstthemachine%2FZE15-CO-CircuitPython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageagainstthemachine%2FZE15-CO-CircuitPython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ageagainstthemachine","download_url":"https://codeload.github.com/ageagainstthemachine/ZE15-CO-CircuitPython/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399895,"owners_count":20932876,"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":["carbon-monoxide","carbon-monoxide-gas-sensor","carbon-monoxide-sensor","circuitpython","circuitpython-library","circuitpython-project","winsen","ze15-co"],"created_at":"2025-02-11T23:58:27.484Z","updated_at":"2025-04-05T20:36:27.632Z","avatar_url":"https://github.com/ageagainstthemachine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZE15-CO CircuitPython Library\n\n## Overview\nThis repository contains a CircuitPython library for interfacing with the ZE15-CO Carbon Monoxide Sensor by Winsen using a UART connection. The library is optimized for cooperative multitasking and provides support for both sensor modes: **Initiative Upload Mode** and **Q\u0026A Mode**.\n\n**Datasheet:** [ZE15-CO Official Datasheet](http://winsen-sensor.com/d/files/ZE15-CO.pdf)\n\n## Features\n- Supports both Initiative Upload Mode and Q\u0026A Mode for sensor data retrieval.\n- Checksum validation to ensure data integrity.\n- Automatic resynchronization in case of misaligned packets.\n- Non-blocking implementation to maintain system responsiveness.\n- Debug mode for detailed troubleshooting output.\n\n## Library Installation\nTo use this library, copy the `ze15.py` file to the `lib` directory of your CircuitPython board.\n\n## Usage\n### Importing the Library\n```python\nfrom ze15 import ZE15CO\n```\n\n### Initializing the Sensor\n```python\nsensor = ZE15CO(rx=board.GP1, tx=board.GP0, mode=ZE15CO.INITIATIVE_MODE, debug=False, warmup_time=10)\n```\n**Parameters:**\n- `rx`: UART RX pin.\n- `tx`: UART TX pin.\n- `mode`: Operation mode (`ZE15CO.INITIATIVE_MODE` or `ZE15CO.QNA_MODE`).\n- `debug`: Enable or disable debug messages (default: `False`).\n- `warmup_time`: Warm-up time in seconds before sensor begins reading (default: `10s`).\n\n## Operating Modes\n### Initiative Upload Mode\nIn this mode, the ZE15-CO sensor automatically transmits data every second.\n\n#### Example Usage\n```python\nsensor = ZE15CO(rx=board.GP1, tx=board.GP0, mode=ZE15CO.INITIATIVE_MODE)\nco_ppm = sensor.read_co()\nprint(f\"CO Concentration: {co_ppm:.1f} ppm\")\n```\n\n### Q\u0026A Mode\nIn this mode, the microcontroller must send a request to the sensor and then wait for a response.\n\n#### Example Usage\n```python\nsensor = ZE15CO(rx=board.GP1, tx=board.GP0, mode=ZE15CO.QNA_MODE)\nco_ppm = sensor.read_co()\nprint(f\"CO Concentration: {co_ppm:.1f} ppm\")\n```\n\n## Data Format and Protocol\nThe ZE15-CO sensor communicates using a 9-byte UART packet format. The format differs slightly between modes.\n\n### Q\u0026A Mode Request Format\n```\n| Byte|0   |1   |2   |3   |4   |5   |6   |7   |8   |\n|--------------------------------------------------|\n| Data|0xFF|0x01|0x86|0x00|0x00|0x00|0x00|0x00|CHK |\n```\n#### Byte Description:\n- **Byte 0 (0xFF):** Start byte.\n- **Byte 1 (0x01):** Command identifier (read gas concentration).\n- **Byte 2 (0x86):** Data type (CO gas request command).\n- **Bytes 3-7 (0x00):** Reserved, always zero.\n- **Byte 8 (CHK):** Checksum for validation.\n\n### Q\u0026A Mode Response Format\n```\n| Byte|0   |1   |2   |3   |4   |5   |6   |7   |8   |\n|--------------------------------------------------|\n| Data|0xFF|0x86|HB  |LB  |0x00|0x00|0x00|0x00|CHK |\n```\n#### Byte Description:\n- **Byte 0 (0xFF):** Start byte.\n- **Byte 1 (0x86):** Command echo (confirming CO gas response).\n- **Bytes 2-3 (HB, LB):** High and low bytes of CO concentration.\n- **Bytes 4-7 (0x00):** Reserved, always zero.\n- **Byte 8 (CHK):** Checksum for validation.\n\n### Initiative Upload Mode Format\n```\n| Byte|0   |1   |2   |3   |4   |5   |6   |7   |8   |\n|--------------------------------------------------|\n| Data|0xFF|0x04|0x03|0x01|HB  |LB  |0x13|0x88|CHK |\n```\n#### Byte Description:\n- **Byte 0 (0xFF):** Start byte.\n- **Byte 1 (0x04):** Gas type identifier (CO gas).\n- **Byte 2 (0x03):** Measurement unit (ppm).\n- **Byte 3 (0x01):** Decimal places (0.1 ppm resolution).\n- **Bytes 4-5 (HB, LB):** High and low bytes of CO concentration.\n- **Bytes 6-7 (0x13, 0x88):** Full range (5000 ppm fixed value).\n- **Byte 8 (CHK):** Checksum for validation.\n\n### CO Concentration Calculation\n```\nCO ppm = ((High Byte \u003c\u003c 8) | Low Byte) * 0.1\n```\n#### Calculation Steps:\n1. The high byte (`HB`) is shifted left by 8 bits to represent the most significant part of the value.\n2. The low byte (`LB`) is added to this shifted value, forming a 16-bit integer.\n3. This integer value is then multiplied by 0.1 to apply the sensor's scaling factor.\n\n### Checksum Calculation\n```\nCHK = (0xFF - (Sum of bytes 1 through 7) + 1) \u0026 0xFF\n```\n#### Calculation Steps:\n1. Sum **bytes 1 through 7** of the response.\n2. Subtract this sum from **0xFF**.\n3. Add **1** to the result.\n4. Mask to **8 bits** using `\u0026 0xFF` to ensure overflow does not affect the result.\n\n## Test Programs\n### Initiative Upload Mode Test\nThis example ([`code.py`](\u003cexamples/Initiative-Upload-Mode/code.py\u003e)) program continuously reads the CO concentration from the sensor.\n\n### Q\u0026A Mode Test\nThis example ([`code.py`](\u003cexamples/QA-Mode/code.py\u003e)) program requests and retrieves CO concentration data when needed.\n\n## Debug Mode\nFor troubleshooting, enable debug mode when initializing the sensor:\n```python\nsensor = ZE15CO(rx=board.GP1, tx=board.GP0, mode=ZE15CO.QNA_MODE, debug=True)\n```\nThis will print additional information such as raw data received, checksum validation, and misalignment handling.\n\n## License\nThis library is provided under the **GPL-3.0 License**. See [`LICENSE`](\u003cLICENSE\u003e) for details.\n\n## Contributions\nContributions are welcome. Feel free to submit pull requests or report issues with the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fageagainstthemachine%2Fze15-co-circuitpython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fageagainstthemachine%2Fze15-co-circuitpython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fageagainstthemachine%2Fze15-co-circuitpython/lists"}