diff --git a/README.md b/README.md index fde2b63..b4d3a53 100644 --- a/README.md +++ b/README.md @@ -3,27 +3,30 @@ ## Features -* Continuously tested on [Raspberry Pi](https://raspberrypi.org), +- Continuously tested on [Raspberry Pi](https://raspberrypi.org), [C.H.I.P.](https://getchip.com/) and Windows 10 via [gohci](https://github.com/periph/gohci). -* Interfaces: I²C, SPI, gpio (both low latency memory mapped registers and +- Interfaces: I²C, SPI, gpio (both low latency memory mapped registers and zero-CPU edge detection), 1-wire and more. -* Devices: apa102, bme280, ds18b20, ssd1306, tm1637, and more coming. +- Devices: apa102, bme280, ds18b20, ssd1306, tm1637, and more coming. ## Quick links -* [doc/users/](doc/users/) for ready-to-use tools. -* [doc/apps/](doc/apps/) to use `periph` as a library. The complete API - documentation, including examples, is at +- [doc/users/](https://periph.io/doc/users/) for ready-to-use tools. +- [doc/apps/](https://periph.io/doc/apps/) to use `periph` as a library. The + complete API documentation, including examples, is at [![GoDoc](https://godoc.org/periph.io/x/periph?status.svg)](https://godoc.org/periph.io/x/periph). -* [doc/drivers/](doc/drivers/) to expand the list of supported hardware. +- [doc/drivers/](https://periph.io/doc/drivers/) to expand the list of supported + hardware. ## Users -periph includes [many ready-to-use tools](cmd/)! See [doc/users/](doc/users/) -for more info on configuring the host and using the included tools. +periph includes [many ready-to-use +tools](https://github.com/google/periph/tree/master/cmd/)! See +[doc/users/](https://periph.io/doc/users/) for more info on configuring the host +and using the included tools. ```bash # Retrieve and install all the commands at once: @@ -39,9 +42,9 @@ gpio-list ## Application developers -For [application developers](doc/apps/), `periph` provides OS-independent bus -interfacing. It really tries hard to _get out of the way_. Here's the canonical -"toggle a LED" sample: +For [application developers](https://periph.io/doc/apps/), `periph` provides +OS-independent bus interfacing. It really tries hard to _get out of the way_. +Here's the canonical "toggle a LED" sample: ```go @@ -64,12 +67,15 @@ func main() { The following are synonyms, use the form you prefer: -* Runtime discovery: - * [`gpio.ByNumber(13)`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByNumber) or [`gpio.ByName("13")`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByName) - * [`gpio.ByName("GPIO13")`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByName) -* Using global variables: - * [`rpi.P1_33`](https://godoc.org/periph.io/x/periph/host/rpi#/P1_33) to select the pin via its position on the board - * [`bcm283x.GPIO13`](https://godoc.org/periph.io/x/periph/host/bcm283x/#GPIO13) +- Runtime discovery: + - [`gpio.ByNumber(13)`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByNumber) + or + [`gpio.ByName("13")`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByName) + - [`gpio.ByName("GPIO13")`](https://godoc.org/periph.io/x/periph/conn/gpio/#ByName) +- Using global variables: + - [`rpi.P1_33`](https://godoc.org/periph.io/x/periph/host/rpi#/P1_33) to + select the pin via its position on the board + - [`bcm283x.GPIO13`](https://godoc.org/periph.io/x/periph/host/bcm283x/#GPIO13) This example uses basically no CPU: the `Out()` call doesn't call into the kernel. Instead it directly changes the GPIO memory mapped register. @@ -77,43 +83,47 @@ kernel. Instead it directly changes the GPIO memory mapped register. ### Samples -See [doc/apps/SAMPLES.md](doc/apps/SAMPLES.md) for more examples. +See [doc/apps/samples/](https://periph.io/doc/apps/samples/) for more examples. ## Contributions `periph` provides an extensible driver registry and common bus interfaces which -are explained in more details at [doc/drivers/](doc/drivers/). `periph` is -designed to work well with drivers living in external repositories so you are -not _required_ to fork the periph repository to load out-of-tree drivers for -your platform. +are explained in more details at [doc/drivers/](https://periph.io/doc/drivers/). +`periph` is designed to work well with drivers living in external repositories +so you are not _required_ to fork the periph repository to load out-of-tree +drivers for your platform. -**Every commit is [tested on real hardware](doc/drivers/CONTRIBUTING.md#testing) -via [gohci](https://github.com/periph/gohci) workers.** +**Every commit is [tested on real +hardware](https://periph.io/doc/drivers/contributing/#testing) via +[gohci](https://github.com/periph/gohci) workers.** We gladly accept contributions for documentation improvements and from device driver developers via GitHub pull requests, as long as the author has signed the Google Contributor License. Please see -[doc/drivers/CONTRIBUTING.md](doc/drivers/CONTRIBUTING.md) for more details. +[doc/drivers/contributing/](https://periph.io/doc/drivers/contributing/) for +more details. ## Philosophy 1. Optimize for simplicity, correctness and usability in that order. - * e.g. everything, interfaces and structs, uses strict typing, there's no + - e.g. everything, interfaces and structs, uses strict typing, there's no `interface{}` in sight. -2. OS agnostic. Clear separation of interfaces in [conn/](conn/), - enablers in [host/](host) and device drivers in [devices/](devices/). - * e.g. no devfs or sysfs path in sight. - * e.g. conditional compilation enables only the relevant drivers to be loaded +2. OS agnostic. Clear separation of interfaces in + [conn/](https://godoc.org/periph.io/x/periph/conn), + enablers in [host/](https://godoc.org/periph.io/x/periph/host) and device + drivers in [devices/](https://godoc.org/periph.io/x/periph/devices). + - e.g. no devfs or sysfs path in sight. + - e.g. conditional compilation enables only the relevant drivers to be loaded on each platform. 3. ... yet doesn't get in the way of platform specific code. - * e.g. A user can use statically typed global variables + - e.g. A user can use statically typed global variables [rpi.P1_3](https://godoc.org/periph.io/x/periph/host/rpi#pkg-variables), [bcm283x.GPIO2](https://godoc.org/periph.io/x/periph/host/bcm283x#Pin) to refer to the exact same pin on a Raspberry Pi. 3. The user can chose to optimize for performance instead of usability. - * e.g. + - e.g. [apa102.Dev](https://godoc.org/periph.io/x/periph/devices/apa102#Dev) exposes both high level [draw.Image](https://golang.org/pkg/image/draw/#Image) to draw an image and @@ -121,16 +131,16 @@ Google Contributor License. Please see 24 bits pixels. The user chooses. 4. Use a divide and conquer approach. Each component has exactly one responsibility. - * e.g. instead of having a driver per "platform", there's a driver per + - e.g. instead of having a driver per "platform", there's a driver per "component": one for the CPU, one for the board headers, one for each bus and sensor, etc. 5. Extensible via a [driver registry](https://godoc.org/periph.io/x/periph#Register). - * e.g. a user can inject a custom driver to expose more pins, headers, etc. + - e.g. a user can inject a custom driver to expose more pins, headers, etc. A USB device (like an FT232H) can expose headers _in addition_ to the headers found on the host. 6. The drivers must use the fastest possible implementation. - * e.g. both + - e.g. both [allwinner](https://godoc.org/periph.io/x/periph/host/allwinner) and [bcm283x](https://godoc.org/periph.io/x/periph/host/bcm283x) @@ -141,8 +151,9 @@ Google Contributor License. Please see ## Authors `periph` was initiated by [Marc-Antoine Ruel](https://github.com/maruel). The -full list of contributors is in [AUTHORS](AUTHORS) and -[CONTRIBUTORS](CONTRIBUTORS). +full list of contributors is in +[AUTHORS](https://github.com/google/periph/blob/master/AUTHORS) and +[CONTRIBUTORS](https://github.com/google/periph/blob/master/CONTRIBUTORS). ## Disclaimer diff --git a/experimental/devices/README.md b/experimental/devices/README.md index 317d8a9..b00ec0b 100644 --- a/experimental/devices/README.md +++ b/experimental/devices/README.md @@ -2,4 +2,4 @@ You are welcome to send PR (pull request) to add experimental device drivers here. Please follow the instructions in -[CONTRIBUTING.md](../../doc/drivers/CONTRIBUTING.md). +[doc/drivers/contributing/](https://periph.io/doc/drivers/contributing/).