{"id":15290591,"url":"https://github.com/warthog618/gpio","last_synced_at":"2025-04-04T15:06:52.848Z","repository":{"id":57493503,"uuid":"81275560","full_name":"warthog618/gpio","owner":"warthog618","description":"A native Go library for Raspberry Pi GPIO","archived":false,"fork":false,"pushed_at":"2024-10-07T02:23:10.000Z","size":106,"stargazers_count":129,"open_issues_count":0,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T14:06:52.439Z","etag":null,"topics":["go","golang","golang-library","gpio","interrupts","pin-level","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Go","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/warthog618.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":"2017-02-08T01:54:26.000Z","updated_at":"2025-03-18T08:03:40.000Z","dependencies_parsed_at":"2024-11-14T19:02:02.947Z","dependency_job_id":"db0fcf7d-1879-4d69-9e74-d66203d6aa35","html_url":"https://github.com/warthog618/gpio","commit_stats":{"total_commits":76,"total_committers":2,"mean_commits":38.0,"dds":"0.013157894736842146","last_synced_commit":"c1ae5d4d9dd9ebdde0157569f56032a6642cf06f"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warthog618%2Fgpio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warthog618%2Fgpio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warthog618%2Fgpio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warthog618%2Fgpio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/warthog618","download_url":"https://codeload.github.com/warthog618/gpio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198449,"owners_count":20900079,"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":["go","golang","golang-library","gpio","interrupts","pin-level","raspberry-pi"],"created_at":"2024-09-30T16:08:43.203Z","updated_at":"2025-04-04T15:06:52.830Z","avatar_url":"https://github.com/warthog618.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gpio\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/warthog618/gpio/go.yml?logo=github\u0026branch=master)](https://github.com/warthog618/gpio/actions/workflows/go.yml)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/warthog618/gpio)\n[![Go Report Card](https://goreportcard.com/badge/github.com/warthog618/gpio)](https://goreportcard.com/report/github.com/warthog618/gpio)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/warthog618/gpio/blob/master/LICENSE)\n\nGPIO library for the Raspberry Pi.\n\n**gpio** is a Go library for accessing\n[GPIO](http://elinux.org/Rpi_Low-level_peripherals) pins on the [Raspberry\nPi](https://en.wikipedia.org/wiki/Raspberry_Pi).\n\nThe library was inspired by and borrows from\n[go-rpio](https://github.com/stianeikeland/go-rpio), which is fast but lacks\ninterrupt support, and [embd](https://github.com/kidoman/embd), which supports\ninterrupts, but uses sysfs for read/write and has a far broader scope than I\nrequire.\n\nThis library does not support the Pi5, and never will.\n\n## :warning: Deprecation Warning :warning:\n\nThis library relies on the sysfs GPIO interface which is deprecated in the Linux\nkernel and is due for removal during 2020.  Without sysfs, the watch/interrupt\nfeatures of this library will no longer work.\n\nThe sysfs GPIO interface has been superceded in the Linux kernel by the GPIO\ncharacter device.  The newer API is sufficiently different that reworking this\nlibrary to use that API is not practical.  Instead I have written a new library,\n[**gpiocdev**](https://github.com/warthog618/go-gpiocdev), that provides the same\nfunctionality as this library but using the GPIO character device.\n\nThere are a couple of downsides to switching to **gpiocdev**:\n\n- The API is quite different, mostly due to the differences in the underlying\n  APIs, so it is not a plugin replacement - you will need to do some code\n  rework.\n- It is also slightly slower for both read and write as all hardware access is\n  now via kernel calls rather than via hardware registers.  However, if that is\n  an issue for you then you probably should be writing a kernel device driver\n  for your use case rather than trying to do something in userspace.\n- It requires a recent Linux kernel for full functionality.  While the GPIO\n  character device has been around since v4.8, the bias and reconfiguration\n  capabilities required to provide functional equivalence to **gpio** were only\n  added in v5.5.\n\nThere are several benefits in the switch:\n\n- **gpiocdev** is not Raspberry Pi specific, but will work on any platform where\n  the GPIO chip is supported by the Linux kernel, so code using **gpiocdev** is\n  more portable.\n- **gpio** writes directly to hardware registers so it can conflict with other\n  kernel drivers.  The **gpiocdev** accesses the hardware internally using the same\n  interfaces as other kernel drivers and so should play nice with them.\n- **gpiocdev** supports Linux GPIO line labels, so you can find your line by name\n  (assuming it has been named by device-tree).\n- and of course, it will continue to work beyond 2020.\n\nI've already ported all my projects that were using **gpio** to **gpiocdev** and\nstrongly suggest that you do the same.\n\n## Features\n\nSupports the following functionality:\n\n- Pin Mode/Direction (Input / Output)\n- Write (High / Low)\n- Read (High / Low)\n- Pullups (Up / Down / None)\n- Watches/Interrupts (Rising/Falling/Both)\n\n## Usage\n\n```go\nimport \"github.com/warthog618/gpio\"\n```\n\n### Library Initialization\n\nOpen memory range for GPIO access in /dev/gpiomem\n\n```go\nerr := gpio.Open()\n```\n\nCleanup when done\n\n```go\ngpio.Close()\n```\n\n### Pin Initialization\n\nA Pin object is constructed using the *NewPin* function. The Pin object is then\nused for all operations on that pin. Note that the pin number refers to the BCM\nGPIO pin, not the physical pin on the Raspberry Pi header. Pin 4 here is exposed\non the pin header as physical pin 7 (J8 7). Mappings are provided from Raspberry\nPi J8 header pin names to BCM GPIO numbers, using the form J8pX.\n\n```go\npin := gpio.NewPin(4)\npin := gpio.NewPin(gpio.J8p7) // Using Raspberry Pi J8 mapping.\n```\n\nThere is no need to cleanup a pin if you no longer need to use it, unless it has\nWatches set in which case you should remove the *Watch*.\n\n### Mode\n\nThe pin mode controls whether the pin is an input or output.  The existing mode\ncan be read back.\n\n```go\nmode := pin.Mode()\npin.Output()               // Set mode to Output\npin.Input()                // Set mode to Input\npin.SetMode(gpio.Output)   // Alternate syntax\n```\n\nTo prevent output glitches, the pin level can be set using *High*/*Low*/*Write*\nbefore the pin is set to Output.\n\n### Input\n\n```go\nres := pin.Read()  // Read state from pin (High / Low)\n```\n\n### Output\n\n```go\npin.High()              // Set pin High\npin.Low()               // Set pin Low\npin.Toggle()            // Toggle pin (Low -\u003e High -\u003e Low)\n\npin.Write(gpio.High)    // Alternate syntax\n```\n\nAlso see example [example/blinker/blinker.go](example/blinker/blinker.go)\n\n### Pullups\n\nPull up state can be set using:\n\n```go\npin.PullUp()\npin.PullDown()\npin.PullNone()\n\npin.SetPull(gpio.PullUp)  // Alternate syntax\n```\n\nUnlike the Mode, the pull up state cannot be read back from hardware, so there is no *Pull* function.\n\n### Watches\n\nThe state of an input pin can be watched and trigger calls to handler functions.\n\nThe watch can be on rising or falling edges, or both.\n\nThe handler function is passed the triggering pin.\n\n```go\nfunc handler(*Pin) {\n  // handle change in pin value\n}\npin.Watch(gpio.EdgeFalling,handler)    // Call handler when pin changes from High to Low.\n\npin.Watch(gpio.EdgeRising,handler)     // Call handler when pin changes from Low to High.\n\npin.Watch(gpio.EdgeBoth,handler)       // Call handler when pin changes\n```\n\nA watch can be removed using the *Unwatch* function.\n\n```go\npin.Unwatch()\n```\n\n## Tools\n\nA command line utility, **gppiio**, is provided to allow manual and scripted\ncontrol of GPIO pins:\n\n```sh\n$ ./gppiio\ngppiio is a utility to control Raspberry Pi GPIO pins\n\nUsage:\n  gppiio [flags]\n  gppiio [command]\n\nAvailable Commands:\n  detect      Identify the GPIO chip\n  get         Read the level of a pin or pins\n  help        Help about any command\n  mode        Read the functional mode of a pin or pins\n  mon         Monitor the level of a pin or pins\n  pull        Set the pull direction of a pin or pins\n  set         Set the level of a pin or pins\n  version     Display the version\n\nFlags:\n  -h, --help      help for gppiio\n\nUse \"gppiio [command] --help\" for more information about a command.\n```\n\n## Examples\n\nRefer to the [examples](example) for more examples of usage.\n\nExamples can be cross-compiled from other platforms using\n\n```sh\nGOOS=linux GOARCH=arm GOARM=6 go build\n```\n\n## Tests\n\nThe library is fully tested, other than some error cases that are difficult to test.\n\nThe tests are intended to be run on a Raspberry Pi with J8 pin 7 floating and\nwith pins 15 and 16 tied together, possibly using a jumper across the header.\nThe tests set J8 pin 16 to an output so **DO NOT** run them on hardware where\nthat pin is being externally driven.\n\nTests have been run successfully on Raspberry Pi B (Rev 1 and Rev 2), B+, Pi2 B,\nPi4 B, and Pi Zero W.  The library should also work on other Raspberry Pi\nvariants, I just don't have any available to test.\n\nThe tests can be cross-compiled from other platforms using\n\n```sh\nGOOS=linux GOARCH=arm GOARM=6 go test -c\n```\n\nLater Pis can also use ARM7 (GOARM=7).\n\n### Benchmarks\n\nThe tests include benchmarks on reads and writes.  Reading pin levels through sysfs is provided for comparison.\n\nThese are the results from a Raspberry Pi Zero W built with Go 1.13:\n\n```sh\n$ ./gpio.test -test.bench=.*\ngoos: linux\ngoarch: arm\npkg: github.com/warthog618/gpio\nBenchmarkRead                  9485052           124 ns/op\nBenchmarkWrite                18478959          58.8 ns/op\nBenchmarkToggle               16695492          72.4 ns/op\nBenchmarkInterruptLatency         2348        453248 ns/op\nBenchmarkSysfsRead               32983         31004 ns/op\nBenchmarkSysfsWrite              17192         69840 ns/op\nBenchmarkSysfsToggle             17341         62962 ns/op\n\nPASS\n```\n\n## Prerequisites\n\nThe library assumes Linux, and has been tested on Raspbian Jessie, Stretch and Buster.\n\nThe library targets all models of the Raspberry Pi, upt to and including the Pi\n4B.  Note that the Raspberry Pi Model B Rev 1.0 has different pinouts, so the J8\nmappings are incorrect for that particular revision.\n\nThis library utilizes /dev/gpiomem, which must be available to the current user.\nThis is generally available in recent Raspian releases.\n\nThe library also utilizes the sysfs GPIO to support interrupts on changes to\ninput pin values.  The sysfs is not used to access the pin values, as the\ngpiomem approach is orders of magnitude faster (refer to the benchmarks).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarthog618%2Fgpio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwarthog618%2Fgpio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarthog618%2Fgpio/lists"}