SwiftyGPIO

<p align="center" style="padding-bottom:50px;"> <img width="500" height="200" src="logo.svg" alt="SwiftyGPIO"/> <br/> <a href="https://raw.githubusercontent.com/uraimo/SwiftyGPIO/master/LICENSE"><img src="http://img.shields.io/badge/License-MIT-blue.svg?style=flat"/></a> <a href="https://developer.apple.com/swift"><img src="https://img.shields.io/badge/Swift-5.x-orange.svg?style=flat"/></a> <a href="https://slackpass.io/swift-arm"><img src="https://img.shields.io/badge/Slack-swift/arm-red.svg?style=flat"/></a> <a href="https://travis-ci.org/uraimo/SwiftyGPIO"><img src="https://travis-ci.org/uraimo/SwiftyGPIO.svg?branch=master" /></a> </p> <p align="center"> <i>A Swift library for hardware projects on Linux/ARM boards with support for GPIOs/SPI/I2C/PWM/UART/1Wire.</i> </p>

Summary

This library provides an easy way to interact with external sensors and devices using the digital GPIOs, SPI/I2C interfaces, 1-Wire buses, PWM signals and serial ports that boards like the Raspberry Pi provide, on Linux using Swift.

Like Android Things or similar libraries in Python, SwiftyGPIO provides the basic functionalities you'll need to control different devices: sensors, displays, input devices like joypads, RGB led strips and matrices.

You'll be able to configure port attributes and read/write the current GPIOs value, use the SPI interfaces (via hardware if your board provides them or using software big-banging SPI), comunicate over a bus with I2C, generate a PWM to drive external displays, servos, leds and more complex sensors, interact with devices that expose UART serial connections using AT commands or custom protocols, and finally connect to 1-Wire devices.

While you'll still be able to develop your project with Xcode or another IDE, the library is built to run exclusively on Linux ARM Boards (RaspberryPis, BeagleBones, ODROIDs, OrangePis, etc...).

Examples of device libraries and complete projects built using SwiftyGPIO that you can use as inspiration for your own DIY hardware projects are listed below, have fun!

Content:

• Supported Boards
• Installation
• Your First Project: Blinking Leds And Sensors
• Usage
  • GPIO
  • SPI
  • I2C
  • PWM
  • Pattern-based signal generator via PWM
  • UART
  • 1-Wire
• Examples
• Built with SwiftyGPIO
  • Device Libraries
  • Awesome Projects
  • Support Libraries
• Additional documentation

Supported Boards

The following boards are supported and have been tested with recent releases of Swift:

• Raspberry Pi 4, 4B
• Raspberry Pi 3, 3A+, 3B+
• Raspberry Pi 2 (Thanks to @iachievedit)
• Raspberry Pi Zero 2 W
• Raspberry Pi Zero W
• Raspberry Pi Zero (Thanks to @MacmeDan)
• Raspberry Pi Classic A,B,A+,B+ Rev1/Rev2
• BeagleBones (Thanks to @hpux735)
• OrangePi (Thanks to @colemancda)
• OrangePi Zero (Thanks to @eugeniobaglieri)
• Asus Tinkerboard (Thanks to Ernesto Lo Valvo)
• C.H.I.P.

But basically everything that has an ARMv7/8+Ubuntu/Debian/Raspbian or an ARMv6+Raspbian/Debian should work if you can run Swift on it.

Please keep in mind that Swift on ARM is a completely community-driven effort, and that there are a multitude of possible board+OS configurations, don't expect that everything will work right away on every configuration even if most of the times it does, especially if you are the first to try a new configuration or board.

Installation

To use this library, you'll need a Linux ARM(ARMv7/8 or ARMv6) board with Swift 3.x/4.x/5.x.

If you have a RaspberryPi (A,B,A+,B+,Zero,ZeroW,2,3,4) with Ubuntu or Raspbian, get Swift 5.x from here or follow the instruction from buildSwiftOnARM to build it yourself in a few hours.

I always recommend to try one of the latest binaries available (either Ubuntu or Raspbian) before putting in the time to compile it yourself, those binaries could(and do most of the times) also work on other Debian-bases distibutions and on different boards.

An alternative way to get these Swift binaries on your Raspberry Pi is through the Swift on Balena project that provides well organized IoT focused Docker images.

You can also setup a cross-compiling toolchain and build ARM binaries (Ubuntu/Raspbian) from a Mac, thanks again to the work of Helge Heß (and Johannes Weiß for implementing it in SPM), read more about that here.

To start your project add SwiftyGPIO as a dependency in your Package.swift:

// swift-tools-version:4.0
import PackageDescription

let package = Package(
    name: "light",
    dependencies: [
         .package(url: "https://github.com/uraimo/SwiftyGPIO.git", from: "1.0.0")
    ]
)

And then build with swift build.

The compiler will create an executable under .build/debug/MyProject.

IMPORTANT: Like every library using GPIOs/SPI/I2C/etc..., if your OS does not come with a predefined user group to access these functionalities, you'll need to run your application with root privileges using sudo. If you are using a RaspberryPi with a Raspbian or a recent Ubuntu (from 16.04 Xenial onward) implementing /dev/gpiomem, sudo will be not required to use basic GPIOs, just launch your application calling the executable built by the compiler.

On misconfigured systems, features like the listeners may require root privileges too and advanced features like PWM sadly always require root privileges.

Alternatively, a specific user group for gpio access can be configured manually as shown here or in this answer on stackoverflow. After following those instruction, remember to add your user (e.g. pi) to the gpio group with sudo usermod -aG gpio pi and to reboot so that the changes you made are applied.

<a href="#first"></a>

Your First Project: Blinking leds and sensors

If you prefer starting with a real project instead of just reading documentation, you'll find some ready to run examples under Examples/ and more than a few tutorials, full projects and videos available online:

• Video: Swift Without Screens - Powering Connected Devices - Talk by Marc Aupont at try! Swift NYC 2019 Conference
• Video: Swift Hardware Hacking, #2 - Talk by Sally Shepard at try! Swift Tokyo 2019 Conference.
• Video: SwiftNIO on the Raspberry PI,#2 - Talk by Helge Heß at Serverside.swift 2018 Conference.
• Video: SwiftyPi - Talk by Kate Castellano at try! Swift Tokyo 2018.
• Video: Swift for IoT - Talk by Subhransu Behera and Kheng Meng Yeo at iOS Conf SG 2016.
• Swift on Raspberry projects at Woolsey Workshop, #2 - A series of tutorials and some example projects from John Woolsey.
• Swift Development with Raspberry Pi, #2 - A series of popular posts by Piotr Gorzelany.
• Accessing RaspberryPi GPIO pins with Swift - A great step by step guide by Cameron Perry.

Usage

Currently, SwiftyGPIO expose GPIOs, SPIs(if not available a bit-banging VirtualSPI can be created), I2Cs, PWMs, 1-Wire and UART ports, let's see how to use them.

GPIO

Let's suppose we are using a Raspberry 3 board and have a led connected between the GPIO pin P2 (possibly with a resistance of 1K Ohm or so in between) and GND and we want to turn it on.

Note that SwiftyGPIO uses the raw Broadcom numbering scheme (described here) to assign a number to each pin.

First, we need to retrieve the list of GPIOs available on the board and get a reference to the one we want to modify:

import SwiftyGPIO

let gpios = SwiftyGPIO.GPIOs(for:.RaspberryPi3)
var gp = gpios[.P2]!

The following are the possible values for the predefined boards:

• .RaspberryPiRev1 (Pi A,B Revision 1, pre-2012, 26 pin header)
• .RaspberryPiRev2 (Pi A,B Revision 2, post-2012, 26 pin header)
• .RaspberryPiPlusZero (Raspberry Pi A+ and B+, Raspberry Zero/W, all with a 40 pin header)
• .RaspberryPi2 (Raspberry Pi 2 with a 40 pin header)
• .RaspberryPi3 (Raspberry Pi 3 with a 40 pin header)
• .RaspberryPi4 (Raspberry Pi 4 with a 40 pin header)
• .BeagleBoneBlack (BeagleBone