# TM1637
A modern Python library for interfacing with TM1637-based 4-digit 7-segment LED display modules, using the Linux GPIO character device interface (`gpiod`).
## Overview
The TM1637 is a driver IC commonly used in 4-digit 7-segment LED display modules. This library offers a clean, Pythonic interface for controlling these displays from any Linux-based platform with GPIO support, including Raspberry Pi, BeagleBone, and other single-board computers.
## Features
- Hardware-agnostic implementation using the modern Linux GPIO character device interface
- Automatic detection of the available GPIO chip device for the given clock and data I/O lines
- Uses the official [`libgpiod`](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/) Python bindings: [`gpiod v2`](https://pypi.org/project/gpiod/)
- Text display
- Scrolling text
- Hexadecimal display (0x0000 to 0xffff)
- Number display (-999 to 9999 or two -9 to 99)
- Temperature display (-9 to 99 with degree Celsius or -9.9 to 99.9 with degree)
- Support for decimal point displays through `TM1637Decimal` class
## Installation
```bash
pip install python-tm1637
```
## Requirements
- Python 3.9 or later
- `gpiod` 2.3.0 or later
- Linux-based system with GPIO pins
## Hardware Connections
| TM1637 | Pin |
|----------------|---------------|
| CLK | GPIO X |
| DIO | GPIO Y |
| VCC | 3.3V or 5V |
| GND | Ground |
> where `TM1637(clk=X, dio=Y)`
## Quick Start
```python
import time
import tm1637
# Initialize display connected to GPIO 23 & 24 at /dev/gpiochip4
display = tm1637.TM1637(clk=23, dio=24, chip_path="/dev/gpiochip4")
# Write segments directly
display.write([127, 127, 127, 127]) # 8888
time.sleep(1)
# Turn off all LEDs
display.write([0, 0, 0, 0])
time.sleep(1)
# Display text
display.show("HIYA")
time.sleep(1)
# Display a number
display.number(8888)
time.sleep(1)
```
## API Reference
### `TM1637` Class
#### Constructor
```python
TM1637(clk, dio, *, chip_path="/dev/gpiochip*", brightness=7)
```
- `clk`: GPIO pin number for the clock line
- `dio`: GPIO pin number for the data I/O line
- `brightness`: Initial brightness level (0-7, default: 7)
- `chip_path`: Path to the GPIO chip device (defaults to auto-detection)
#### Properties
- `brightness`: Get or set the display brightness
- `chip_path`: Get the path to GPIO chip device in use
- `clk`: Get the GPIO pin number of the clock line passed to constructor
- `dio`: Get the GPIO pin number of the data I/O line passed to constructor
#### Methods
- `write(segments, pos=0)`: Write raw segments
- `show(string, sep=False)`: Display a string
- `scroll(string, delay=0.25)`: Scroll a string across the display
- `hex(val)`: Display a hexadecimal value (0x0000 to 0xffff)
- `number(num)`: Display an integer value (-999 to 9999)
- `numbers(num1, num2, sep=True)`: Display two integers values (-9 to 99)
- `temperature(num)`: Display a temperature integer value
- `temperature_decimal(num)`: Display a temperature decimal value
#### Static Methods
- `encode_char(char)`: Convert a character to its segment representation
- `encode_digit(digit)`: Convert a digit to its segment representation
- `encode_string(string)`: Convert a string to an array of segments
### `TM1637Decimal` Class
Extends `TM1637` to enable support for display modules having a decimal point after each digit.
#### Static Methods
- `encode_string(string)`: Convert a string [with periods in-between] to an array of segments
## Permissions
To access the GPIO chip device without root permissions, the user must be in the `gpio` group. To add the current user to the `gpio` group:
```bash
sudo usermod -aG gpio $USER
sudo reboot
```
## Examples
### Clock Display
```python
import time
import tm1637
display = tm1637.TM1637(clk=23, dio=24)
colon = True
while True:
time.sleep(1 - time.time()%1)
lt = time.localtime()
display.numbers(lt.tm_hour, lt.tm_min, sep=colon)
colon = not colon
```
### Temperature Display
```python
import tm1637
display = tm1637.TM1637(clk=23, dio=24)
display.temperature(23) # 23*C
display.temperature_decimal(23.5) # 23:5*
```
### Scrolling Text
```python
import tm1637
display = tm1637.TM1637(clk=23, dio=24)
display.scroll("HELLO WORLD", delay=0.1)
```
## License
MIT License - check the [LICENSE](LICENSE) file for details.
## Sources
- [Original MicroPython implementation by Mike Causer](https://github.com/mcauser/micropython-tm1637)
- [Python port for Raspberry Pi by Patrick Palma](https://github.com/depklyon/raspberrypi-tm1637)
Raw data
{
"_id": null,
"home_page": null,
"name": "python-tm1637",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "7, display, gpiod, led, segment, tm1637",
"author": "Asadullah Shaikh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3e/40/840f21818d923fbb9d5cee22ddfd34371cbf4748e351a8f13027c2eaa2f6/python_tm1637-0.1.5.tar.gz",
"platform": null,
"description": "# TM1637\n\nA modern Python library for interfacing with TM1637-based 4-digit 7-segment LED display modules, using the Linux GPIO character device interface (`gpiod`).\n\n## Overview\n\nThe TM1637 is a driver IC commonly used in 4-digit 7-segment LED display modules. This library offers a clean, Pythonic interface for controlling these displays from any Linux-based platform with GPIO support, including Raspberry Pi, BeagleBone, and other single-board computers.\n\n## Features\n\n- Hardware-agnostic implementation using the modern Linux GPIO character device interface\n- Automatic detection of the available GPIO chip device for the given clock and data I/O lines\n- Uses the official [`libgpiod`](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/) Python bindings: [`gpiod v2`](https://pypi.org/project/gpiod/)\n- Text display\n- Scrolling text\n- Hexadecimal display (0x0000 to 0xffff)\n- Number display (-999 to 9999 or two -9 to 99)\n- Temperature display (-9 to 99 with degree Celsius or -9.9 to 99.9 with degree)\n- Support for decimal point displays through `TM1637Decimal` class\n\n## Installation\n\n```bash\npip install python-tm1637\n```\n\n## Requirements\n\n- Python 3.9 or later\n- `gpiod` 2.3.0 or later\n- Linux-based system with GPIO pins\n\n## Hardware Connections\n\n| TM1637 | Pin |\n|----------------|---------------|\n| CLK | GPIO X |\n| DIO | GPIO Y |\n| VCC | 3.3V or 5V |\n| GND | Ground |\n> where `TM1637(clk=X, dio=Y)`\n\n## Quick Start\n\n```python\nimport time\n\nimport tm1637\n\n\n# Initialize display connected to GPIO 23 & 24 at /dev/gpiochip4\ndisplay = tm1637.TM1637(clk=23, dio=24, chip_path=\"/dev/gpiochip4\")\n\n# Write segments directly\ndisplay.write([127, 127, 127, 127]) # 8888\ntime.sleep(1)\n\n# Turn off all LEDs\ndisplay.write([0, 0, 0, 0])\ntime.sleep(1)\n\n# Display text\ndisplay.show(\"HIYA\")\ntime.sleep(1)\n\n# Display a number\ndisplay.number(8888)\ntime.sleep(1)\n```\n\n## API Reference\n\n### `TM1637` Class\n\n#### Constructor\n\n```python\nTM1637(clk, dio, *, chip_path=\"/dev/gpiochip*\", brightness=7)\n```\n\n- `clk`: GPIO pin number for the clock line\n- `dio`: GPIO pin number for the data I/O line\n- `brightness`: Initial brightness level (0-7, default: 7)\n- `chip_path`: Path to the GPIO chip device (defaults to auto-detection)\n\n#### Properties\n- `brightness`: Get or set the display brightness\n- `chip_path`: Get the path to GPIO chip device in use\n- `clk`: Get the GPIO pin number of the clock line passed to constructor\n- `dio`: Get the GPIO pin number of the data I/O line passed to constructor\n\n#### Methods\n\n- `write(segments, pos=0)`: Write raw segments\n- `show(string, sep=False)`: Display a string\n- `scroll(string, delay=0.25)`: Scroll a string across the display\n- `hex(val)`: Display a hexadecimal value (0x0000 to 0xffff)\n- `number(num)`: Display an integer value (-999 to 9999)\n- `numbers(num1, num2, sep=True)`: Display two integers values (-9 to 99)\n- `temperature(num)`: Display a temperature integer value\n- `temperature_decimal(num)`: Display a temperature decimal value\n\n#### Static Methods\n\n- `encode_char(char)`: Convert a character to its segment representation\n- `encode_digit(digit)`: Convert a digit to its segment representation\n- `encode_string(string)`: Convert a string to an array of segments\n\n### `TM1637Decimal` Class\n\nExtends `TM1637` to enable support for display modules having a decimal point after each digit.\n\n#### Static Methods\n\n- `encode_string(string)`: Convert a string [with periods in-between] to an array of segments\n\n## Permissions\n\nTo access the GPIO chip device without root permissions, the user must be in the `gpio` group. To add the current user to the `gpio` group:\n\n```bash\nsudo usermod -aG gpio $USER\nsudo reboot\n```\n\n## Examples\n\n### Clock Display\n\n```python\nimport time\n\nimport tm1637\n\n\ndisplay = tm1637.TM1637(clk=23, dio=24)\n\ncolon = True\nwhile True:\n time.sleep(1 - time.time()%1)\n lt = time.localtime()\n display.numbers(lt.tm_hour, lt.tm_min, sep=colon)\n colon = not colon\n```\n\n### Temperature Display\n\n```python\nimport tm1637\n\n\ndisplay = tm1637.TM1637(clk=23, dio=24)\n\ndisplay.temperature(23) # 23*C\ndisplay.temperature_decimal(23.5) # 23:5*\n```\n\n### Scrolling Text\n\n```python\nimport tm1637\n\n\ndisplay = tm1637.TM1637(clk=23, dio=24)\n\ndisplay.scroll(\"HELLO WORLD\", delay=0.1)\n```\n\n## License\n\nMIT License - check the [LICENSE](LICENSE) file for details.\n\n## Sources\n\n- [Original MicroPython implementation by Mike Causer](https://github.com/mcauser/micropython-tm1637)\n- [Python port for Raspberry Pi by Patrick Palma](https://github.com/depklyon/raspberrypi-tm1637)\n",
"bugtrack_url": null,
"license": null,
"summary": "Library for TM1637-based LED display modules",
"version": "0.1.5",
"project_urls": {
"homepage": "https://github.com/pantheraleo-7/tm1637"
},
"split_keywords": [
"7",
" display",
" gpiod",
" led",
" segment",
" tm1637"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc0dd994eaaaab7047ab01cad5525daeade1ebdb5d6601e47865c972a8a794d3",
"md5": "dc7746b5dbd8b333b4954ac5a941b872",
"sha256": "33661f2c1936297b632d6b61d448df29bb859b7772d0174293af7c904856389f"
},
"downloads": -1,
"filename": "python_tm1637-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc7746b5dbd8b333b4954ac5a941b872",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6474,
"upload_time": "2025-04-18T07:09:00",
"upload_time_iso_8601": "2025-04-18T07:09:00.989782Z",
"url": "https://files.pythonhosted.org/packages/dc/0d/d994eaaaab7047ab01cad5525daeade1ebdb5d6601e47865c972a8a794d3/python_tm1637-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3e40840f21818d923fbb9d5cee22ddfd34371cbf4748e351a8f13027c2eaa2f6",
"md5": "786edd3e420bb07e2b5ebaba4b92091d",
"sha256": "3183f4e5e0823778433391390b54b0ee3cb1b9519a72045f99b2b23fb072eb6d"
},
"downloads": -1,
"filename": "python_tm1637-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "786edd3e420bb07e2b5ebaba4b92091d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5575,
"upload_time": "2025-04-18T07:09:01",
"upload_time_iso_8601": "2025-04-18T07:09:01.983773Z",
"url": "https://files.pythonhosted.org/packages/3e/40/840f21818d923fbb9d5cee22ddfd34371cbf4748e351a8f13027c2eaa2f6/python_tm1637-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-18 07:09:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pantheraleo-7",
"github_project": "tm1637",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "python-tm1637"
}
JSON
