A Swift library for 16x2/20x4 Character LCDs with the HD44780(or clones) controller
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A Swift library for 16x2(aka 1602A), 20x4(aka 2004A) or bigger Character LCDs with an Hitachi HD44780 controller or one of its clones(KS0066, SPLC780D, ST7066U, NT8331D, etc...).

Linux-only Swift 4 compatible License: BSD

LCD with Swift


A Swift library for 16x2(aka 1602A), 20x4(aka 2004A) or bigger Character LCDs with an Hitachi HD44780 controller or one of its clones(KS0066, SPLC780D, ST7066U, NT8331D, etc... 99% of the controllers on the market).

This library will not work with LCDs connected to an additional I2C/SPI driver board (boards with just 5 pins instead of 16 or so).

Also, the RGB backlight is not supported, it could be added in the future if someone is interested.

Supported Boards

Every board supported by SwiftyGPIO: Raspberries, BeagleBones, C.H.I.P., etc...

To use this library, you'll need a Linux ARM board with Swift 3.x/4.x, the old Swift 2.x version of this library is available on a specific branch.

The example below will use a RaspberryPi2 board but you can easily modify the example to use one the the other supported boards.


Please refer to the SwiftyGPIO readme for Swift installation instructions.

Once your board runs Swift, if your version support the Swift Package Manager, you can simply add this library as a dependency of your project and compile with swift build:

let package = Package(
    name: "MyProject",
    dependencies: [
	.Package(url: "https://github.com/uraimo/HD44780CharacterLCD.swift.git", majorVersion: 3),

The directory Examples/RaspberryPi contains a sample project that uses SPM, compile it and run the sample with sudo ./.build/debug/TestLCD.

If SPM is not supported, you'll need to manually download the library and its dependencies:

wget https://raw.githubusercontent.com/uraimo/HD44780CharacterLCD.swift/master/Sources/HD44780CharacterLCD.swift https://raw.githubusercontent.com/uraimo/SwiftyGPIO/master/Sources/SwiftyGPIO.swift https://raw.githubusercontent.com/uraimo/SwiftyGPIO/master/Sources/Presets.swift https://raw.githubusercontent.com/uraimo/SwiftyGPIO/master/Sources/SunXi.swift

And once all the files have been downloaded, create an additional file that will contain the code of your application (e.g. main.swift). When your code is ready, compile it with:

swiftc  *.swift

The compiler will create a main executable.

As everything interacting with GPIOs, if you are not already root, you will need to run that binary with sudo ./main.


In the following usage example i'll use a 20x4 LCD connected to a RaspberryPi 2 as shown below:

HD44780 pins

Before using this as a reference, verify that the pins are the same (A and K could have a different name).

Since the library supports only writes, the R/W pin is connected to GND and since we use a 4bit data mode, the lower 4 data pins are not connected to anything.

The A and K pins are used for the backlight, if you have and RGB backlight LCD, you'll have three pins instead of two. Usually you will just connect K to GND and A to VDD(5V). The V0 pins regulates the display contrast, you could connect it to GND for maximum contrast or you could search the value you prefer with a 20K variable resistor, here i suggest you to use a 470 Ohm resistor connected to GND that will give you a good value of contrast (see pitcure above), if you don't like it feel free to experiment.

And that's all for the LCD connections, just connect the remaining pins to the Raspberry GPIOs as shown in the diagram.

The library needs 6 GPIO Objects created with SwiftyGPIO to initialize the HD44780 class, let's see how to do it on a RaspberryPi 2, we'll use the first 6 gpios on the left side of the header:

import SwiftyGPIO
import HD44780LCD

let gpios = SwiftyGPIO.GPIOs(for: .RaspberryPi2)
var rs = gpios[.P2]!
var e = gpios[.P3]!
var d4 = gpios[.P4]!
var d5 = gpios[.P17]!
var d6 = gpios[.P27]!
var d7 = gpios[.P22]!
let lcd = HD44780LCD(rs:rs,e:e,d7:d7,d6:d6,d5:d5,d4:d4,width:20,height:4)

The screen can be cleared using the clearScreen method:


The cursor, a functionality provided by the HD44780 LCD, points to the position where the next character should be drawn, the cursor can be moved to home (0,0) or to a specific position:


At the moment, cursor related methods do not have a real use case since it's not possible to print a character or a string at the current position (trivial to implement).

To print a string at a given position, use the printString method, the last parameter specifies if the US charset should be used. If the boolean is false, a japanese charset with katakana symbols will be used instead.

lcd.printString(x:0,y:0,what:"Hello From Swift!",usCharSet:true)


Examples are available in the Examples directory.

Projects using this library:


A few missing features:

  • User defined characters not supported (see here)
  • This library only write to the display, reading is not supported
  • RGB backlit LCD variant not supported (can be easily implemented with 3 gpios)