{"id":13667134,"url":"https://github.com/3Qax/SwiftyOLED","last_synced_at":"2025-04-26T15:32:12.761Z","repository":{"id":54691604,"uuid":"190832403","full_name":"3Qax/SwiftyOLED","owner":"3Qax","description":"A Swift library for OLED displays based on SSD1306 and SSD1305 drivers.","archived":false,"fork":false,"pushed_at":"2021-02-03T16:48:15.000Z","size":2077,"stargazers_count":28,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T13:09:00.302Z","etag":null,"topics":["display","iot","oled-display-ssd1306","raspberry-pi","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/3Qax.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}},"created_at":"2019-06-08T01:31:42.000Z","updated_at":"2024-08-06T21:31:18.000Z","dependencies_parsed_at":"2022-08-14T00:10:33.339Z","dependency_job_id":null,"html_url":"https://github.com/3Qax/SwiftyOLED","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3Qax%2FSwiftyOLED","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3Qax%2FSwiftyOLED/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3Qax%2FSwiftyOLED/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3Qax%2FSwiftyOLED/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/3Qax","download_url":"https://codeload.github.com/3Qax/SwiftyOLED/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251008746,"owners_count":21522168,"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":["display","iot","oled-display-ssd1306","raspberry-pi","swift"],"created_at":"2024-08-02T07:00:32.405Z","updated_at":"2025-04-26T15:32:12.089Z","avatar_url":"https://github.com/3Qax.png","language":"Swift","funding_links":[],"categories":["Displays"],"sub_categories":["Networking, IoT, Bus Protocols, …"],"readme":"# SwiftyOLED\n\nA Swift library for OLED displays based on SSD1306 and SSD1305 drivers.\nIt is just a set of functions for handling mentioned aboved drivers.\nIt is __not__ a graphics library. For that I would like to recommend a [SwiftyGFX](https://github.com/3Qax/SwiftyGFX), which I will be using here as an example. However you are free to use your own.\n\n## Getting Started 💡\n\nIn this section you will create your first project\n\n### Prerequisites\n\n* Wire the display\n* Make sure you know to which I2C interface you have wired the display\n* Make sure you are aware of a I2C address of display module you have. For most cases it will be 0x3C or 0x3D. If you are unsure run `sudo apt-get install i2c-tools \u0026\u0026 sudo i2cdetect -y 1`. Confused? [take a look here](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c#testing-i2c-5-14)\n* Create new project with SwiftPM like `swift package init --type executable`\n\n### Dependencies\n\nIn your __Package.swift__ file:\n* Add the following packages as dependencies\n```swift\n.package(url: \"https://github.com/3Qax/SwiftyOLED.git\", from: \"1.0.0\"),\n.package(url: \"https://github.com/3Qax/SwiftyGFX.git\", from: \"1.0.0\"),\n.package(url: \"https://github.com/uraimo/SwiftyGPIO.git\", from: \"1.0.0\"),\n```\n* Show SwiftPM that your target will need those dependencies\n```swift\n.target(\n    name: \"NameOfYourProject\",\n    dependencies: [\"SwiftyOLED\", \"SwiftyGFX\", \"SwiftyGPIO\"]),\n```\n\n### Code\n\nPaste the following code into your source file, which most likely will be in _Sources/NameOfYourProject/**main.swift**_. Change I2C Interface and I2C address if needed. Set width and height of your display according to specification of model you have bought.\n\n```swift\nimport SwiftyOLED\nimport SwiftyGFX\nimport SwiftyGPIO\n\nlet i2cs = SwiftyGPIO.hardwareI2Cs(for: .RaspberryPiPlusZero)!\n// Make sure you entered a correct parameters below\nlet myOLED = OLED(connectedTo: i2cs[1], at: 0x3C, width: 128, height: 32)\n\nlet myText = Text(\"Hello world!\")\n\nmyOLED.draw(points: myText.generatePointsForDrawing())\nmyOLED.display()\n```\n\n### Run\n\nJust do `swift build` and then `swift run`. You should see:\n![Image of Raspberry Pi with PiOLED connected to it on which \"Hello world!\" is visible](https://raw.githubusercontent.com/3Qax/SwiftyOLED/develop/Examples/hello%20world/result.jpg)\nThat's all. It's really that simple! Complete project can be found in _/Examples/hello world/_ folder.\n\n## Usage 🛠\n\n### Initialization\n\nTo create the instance of OLED use the follwoing initializer\n```swift\n    public init(connectedTo interface: I2CInterface, at address: Int, width: Int, height: Int)\n```\nPass the I2C interface that display is connected to and specify at which address device listens.\nEnter the width and height (in px) based on the specification of display you have. Probably it will be 128x32 or 128x64.\nInitialization will fail on runtime if display is unreachable or if given height or width doesn't make sense (exceed driver supported range).\n\n### Drawing\n\nIf you don't feel like writing your graphics library today, take a look at my easy to use graphics library [SwiftyGFX](https://github.com/3Qax/SwiftyGFX). It provides a bunch of primitives like Circles and Rectangles, but is also capable of text rendering. See it's README.md for details.\n\nOnce you've got the reference to the display it's time to draw something!\nThis can be done by calling one of these methods\n```swift\n    public func draw(point: (Int, Int))\n    public func draw(points: [(Int, Int)])\n```\nDoing so changes the color of point or points at given coordinates to white in __local buffer__. This means that __drawn points will be not visible until calling `display()`__.\n\nThe display works in iOS like coordinate system. So:\n* (0, 0) is top left pixel\n* X axis increases to the right\n* Y axis increases downwards\n\nPoint consists of (respectively) x and y coordinates\n\nIf you would like to clean (make black) the __local buffer__ do it like\n```swift\n    public func clear()\n```\nOr if you are on the light side of force this method might come in handy\n```swift\n    public func fill()\n```\n\n### Inversion\n\nIn order to draw things in black on white display use above mentioned  methods and set the display to interprete everything inversly. Logically, `clear()` will make whole local buffer white and drawing would make given points black. It is as simple as calling\n```swift\n    public func set(inversion: Bool)\n```\nBy default it off. You can check wether display is inverted by accessing _read only_ property called `isInverted`.\n\n### Displaying drawn things\n\nOnce you have drawn everything you wanted and want to make it visible call\n```swift\n    public func display()\n```\nThis will make display reflect the actual state of local buffer. After that local buffer will be cleared. The API is designed is such a way, because transfering data over I2C is quite slow operation. Call this method only after you have drawn everything.\n\n### Brightness\n\nThere is even an option to change the brightness by calling\n```swift\n    public func set(brightness: Brightness)\n```\nThere are two recomended setting: `.dimmed` or `.bright`, however if you wish so you can set custom level like `.custom(value: 0x8F)`\n\n### Switching on and off\n\nIf your project requires low power consumption or showing data on display only from time to time take a look at\n```swift\n    public func turn(_ state: State)\n```\nIt allows you to either turn it `.on` or `.off`. Display is configured to display the latest data it have recived on resume (turn on after being turned off). The display after being initialized is automatically turned on. Display's state is stored in _read only_ property called `isOn`.\n\n\n## Performance 💨\n\nPerformance was tested on geniune RaspberryPi ZERO v1.3 running Raspbian Stretch Lite using SwiftyGPIO 1.1.7.\n\n| Display size (px)  | Avarege time of `display()`  |\n|:-------------------:|:---------------------------------:|\n| 96x16                  | 7ms                                        |\n| 128x32                | 16ms                                      |\n| 128x64                | 32ms                                      |\n\n## Contributing 🤝\n\nAny suggestions and contributions are welcome, as long as they are up to scratch.\n\n## Acknowledgments 📣\n\n* This library use, require and rely on [SwiftyGPIO](https://github.com/uraimo/SwiftyGPIO)\n* Big inspiration and a lot of knowledge was taken from a [Adafruit CircuitPython library for SSD1306](https://github.com/adafruit/Adafruit_CircuitPython_SSD1306)\n\n## Datasheets 📚\n\n- [SSD1306 ](https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf)\n- [UG-2832HSWEG02](https://cdn-shop.adafruit.com/datasheets/UG-2832HSWEG02.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3Qax%2FSwiftyOLED","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F3Qax%2FSwiftyOLED","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3Qax%2FSwiftyOLED/lists"}