{"id":15170111,"url":"https://github.com/de-dh/textbox-mpy","last_synced_at":"2026-01-25T01:02:08.516Z","repository":{"id":248667584,"uuid":"829340104","full_name":"de-dh/TextBox-MPY","owner":"de-dh","description":"OOP example. Create simple TextBoxes on OLED/TFT Displays using Micropython on Raspberry Pi Pico","archived":false,"fork":false,"pushed_at":"2024-07-16T10:34:05.000Z","size":272,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-25T12:21:41.444Z","etag":null,"topics":["micropython","rpi-pico","ssd1306","st7735r"],"latest_commit_sha":null,"homepage":"","language":"Python","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/de-dh.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-16T08:30:48.000Z","updated_at":"2024-07-22T13:08:47.000Z","dependencies_parsed_at":"2024-07-16T11:54:32.408Z","dependency_job_id":null,"html_url":"https://github.com/de-dh/TextBox-MPY","commit_stats":null,"previous_names":["de-dh/textbox-mpy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-dh%2FTextBox-MPY","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-dh%2FTextBox-MPY/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-dh%2FTextBox-MPY/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-dh%2FTextBox-MPY/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/de-dh","download_url":"https://codeload.github.com/de-dh/TextBox-MPY/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239195130,"owners_count":19598032,"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":["micropython","rpi-pico","ssd1306","st7735r"],"created_at":"2024-09-27T08:00:36.750Z","updated_at":"2026-01-25T01:02:08.473Z","avatar_url":"https://github.com/de-dh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TextBox-MPY\n\n## Description\n\u003cimg align=\"right\"  src=\"doc/OLED.jpg\" width=\"150\" height=\"auto\" /\u003e\n\nTextBox is used to create simple **boxes with a caption and multiple lines of text** on SSD1306-OLED / ST7735R-TFT displays using FrameBuffer-derived drivers in micropython on Raspberry Pi Pico.\nEach text line is rendered in an individual FrameBuffer. \nThis enables **fast updating** of the screen without flickering.\n\nText lines can easily be added, updated and deleted. \nMultiple TextBoxes can be created on one screen.\n\nI use this for all my projects where I need to display text on an OLED / TFT Display.\nThis way, I don't have to mess around with graphic functions again and again if I want to display text / data.\n\n## Usage\n\n### Installation\n\nAll neccessary files are located in the `/src` folder.\nThe `/src/lib` folder contains the TextBox class for import and a SSD1306-OLED-Driver and a ST7735R-TFT-Driver.\nThe `/lib` folder needs to be copied onto the RPI using Thonny. \n**The other files in the `/src` directory are complete examples demonstrating the use of TextBox on OLED / TFT displays.**\n\nImport TextBox and drivers in your programm:\n```python\nimport ssd1306 # OLED driver\nfrom ST7735R import ST7735R # TFT driver\nfrom TextBox import TextBox, TextBoxOLED, TextBoxTFT # TextBox\nfrom machine import Pin, I2C, SPI # Needed to initialize the displays\n```\n\n### Initialization\n\nFirst, the displays need to be initialized to obtain a display object.\nI use a simple class for that.\n\n\u003cdetails\u003e\n\u003csummary\u003eInitialize OLED Display\u003c/summary\u003e\n\n```python\n\"\"\"OLED Display\nVCC --\u003e VBUS Pin 36 (3.3V)\nGND --\u003e Pin Nr. 3\"\"\"\nDISPLAY_SDA_PIN = const(26)\nDISPLAY_SCL_PIN = const(27)\nDISPLAY_I2C_INSTANCE = const(1)\n\nclass OLED:\n    def __init__(self, scl_pin, sda_pin):\n        self.scl_pin = scl_pin\n        self.sda_pin = sda_pin\n        \n        self.width  = 128\n        self.height = 64\n        \n        # Make sure to use the correct I2C instance (0 or 1)\n        # according to pin map\n        self.i2c = I2C(DISPLAY_I2C_INSTANCE,scl=Pin(self.scl_pin),\n                       sda=Pin(self.sda_pin), freq = 2000000)\n        \n        self.display = ssd1306.SSD1306_I2C(self.width, self.height, self.i2c)\n        self.clear()\n\n    # Returns display object. \n    def display_object(self):\n        return self.display\n    \n    def clear(self):\n        self.display.fill(0)\n        self.display.show()\n```\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eInitialize TFT Display\u003c/summary\u003e\n\n```python\n\"\"\"TFT Display\nVCC --\u003e VBUS Pin 36 (3.3V)\nGND --\u003e Pin Nr. 3\"\"\"\nTFT_MISO_PIN = None # --\u003e not needed\nTFT_CLK_PIN = const(2)  # --\u003e SCK\nTFT_MOSI_PIN = const(3) # --\u003e SDA\nTFT_RST_PIN = const(4) # --\u003e RES\nTFT_DC_PIN = const(5) # --\u003e DC\nTFT_CS_PIN = const(6) # --\u003e CS\nTFT_BLK_PIN = const(7) # --\u003e Backlight\n\nclass TFT():\n    def __init__(self, clk, mosi, miso, cs, dc, rst, blk):\n        self.width = 128\n        self.height = 160\n        \n        self.dc = Pin(dc, Pin.OUT, Pin.PULL_DOWN)\n        self.cs = Pin(cs, Pin.OUT, Pin.PULL_DOWN)\n        self.rst = Pin(rst, Pin.OUT, Pin.PULL_DOWN)\n        \n        self.blk = Pin(blk, Pin.OUT, Pin.PULL_UP)\n        \n        # Turn on backlight.\n        # Brightness may be controlled by PWM.\n        self.blk(1)\n        \n        self.spi = SPI(0, baudrate = 15625000, polarity = 0, phase = 0, sck = Pin(clk),\n                   mosi = Pin(mosi), miso = miso)\n    \n        self.display = ST7735R(self.spi, self.cs, self.dc, self.rst,\n                   height = self.height, width = self.width)\n        \n    # Returns display object.    \n    def display_object(self):\n        return self.display\n    \n    def clear(self):\n        self.display.fill(0)\n        self.display.show()\n```\n\n\u003c/details\u003e\n\nInitialize display and pass the display object to TextBox.\nInitialization is slightly different for OLED and TFT.\n\n\n```python\n    \"\"\" Use with OLED display:\n    Initialize OLED display, then initialize first TextBox and pass display handle. \"\"\"\n    OLED = OLED(DISPLAY_SCL_PIN, DISPLAY_SDA_PIN)\n    BOX_1 = TextBoxOLED(OLED.display_object(), caption = 'Box 1', pos = 0)\n\n\n    \"\"\" Use with TFT display:\n    Initialize TFT display, then initialize first TextBox and pass display handle. \"\"\"\n    TFT = TFT(clk = TFT_CLK_PIN, mosi = TFT_MOSI_PIN, miso = TFT_MISO_PIN,\n                     cs = TFT_CS_PIN, dc = TFT_DC_PIN, rst = TFT_RST_PIN,\n                     blk = TFT_BLK_PIN)\n\n    BOX_1 = TextBoxTFT(TFT.display_object(), caption = 'Ambient Data', pos = 5,\n                        fg_color = (0, 255, 0), bg_color = ((0,) * 3))\n```\n\nAfter initialization, the same commands apply to the OLED and the TFT version.\n\n\n### Add lines\n\nWhen creating lines, a handle is returned representing each line.\nThe handle can be used to address individual lines for later updates or deletion.\nAfter all lines are added, call the `show()` command to draw the box.\nThe dimensions of the box are calculated automatically.\n\n```python\n    \"\"\" Same commands for use with OLED and TFT displays \"\"\"\n    line_1 = BOX_1.add_line('A')\n    line_2 = BOX_1.add_line('B')\n    BOX_1.show()\n```\n\n### Update lines\n\nCall `TextBox.update_line(line_handle, 'New Text')` to update the content of a line or `TextBox.update_caption('New Caption')`.\nOnly the FrameBuffer of the line is updated to enhance performance. An update of the whole screen is not neccessary.\n\n```python\n    \"\"\" Same commands for use with OLED and TFT displays \"\"\"\n    BOX_1.update_line(line_1, 'New Text')\n    BOX_1.update_caption('New Caption')\n```\n\n### Delete lines\n\nCall `TextBox.delete_line(line_handle)` to delete a line. \nThe size of the TextBox is adjusted automatically and the order of the remaining lines is preserved.\nThis causes the whole TextBox to be redrawn.\n\n```python\n    \"\"\" Same commands for use with OLED and TFT displays \"\"\"\n    BOX_1.delete_line(line_1)\n```\n\n### Invert lines\n\nCall `TextBox.invert_color(line_handle)` to swap the foreground and the background color of a text line. \nThis can be used to highlight a line.\n \n```python\n    \"\"\" Same commands for use with OLED and TFT displays \"\"\"\n    BOX_1.invert_line(line_1)\n```\n\n### Box position and height\n\nThe vertical position and the height of a TextBox can be obtained via `TextBox.box_y` and `TextBox.box_h `.\nThis can be used to position a second box underneath an existing box.\n \n```python\n    \"\"\" Same commands for use with OLED and TFT displays \"\"\"\n    # Calculate position of second box.\n    # Place it five pixel below first box.\n    pos_2 = BOX_1.box_y + BOX_1.box_h + 5\n```\n\n## Examples\n\n\u003cimg align=\"left\"  src=\"doc/TFT_OLED_Overview.jpg\" width=\"300\" height=\"auto\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fde-dh%2Ftextbox-mpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fde-dh%2Ftextbox-mpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fde-dh%2Ftextbox-mpy/lists"}