MadDrivers

This MadDrivers library, based on SwiftIO, provides an easy way to use all kinds of devices with your boards. You could directly use the related class to read or write data without worrying about communication details.

Note: This library aims to simplify the way you program all devices, so some uncommon errors or rare situations aren't considered. The SwiftIO library can give messages about the communication and which error occurs if it fails. If you need more detailed results to ensure security, feel free to download and modify the code according to your need.

Drivers

The table below lists the existing drivers and will be updated as time goes on.

We will keep adding more drivers. And your contributions are welcome!

Try examples

Let's start by trying demo projects in the folder Examples.

In the folder Examples, there are folders for different devices. Each folder may have one or several projects to help you get started with each device.

├── Examples
│   ├── ADXL345
│   │   ├── ReadXYZ
│   ├── DS3232
│   │   ├── Alarm
│   │   ├── ReadTime
│   │   ├── Timer
│   ├── IS31FL3731
│   ├── ├── BreathingLED
│   ├── ├── DrawPixels
│   ├── ├── Frame
│   ├── ├── ScrollingText
│   ├── ...

After you download the whole folder, here is a tutorial about running the code on your board.

Use drivers

Take the library SHT3x for example:

1. Create an executable project ReadSHT3x.

2. Open the project and open the file Package.swift.

   MadDrivers has already been added to the dependency by default, thus you can use all drivers in it. However, it's better to specify a specific library to reduce the build time for your project. So change the statement .product(name: "MadDrivers", package: "MadDrivers") to .product(name: "SHT3x", package: "MadDrivers") as shown below.

// swift-tools-version:5.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
    name: "ReadSHT3x",
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(url: "https://github.com/madmachineio/SwiftIO.git", .upToNextMinor(from: "0.0.1")),
        .package(url: "https://github.com/madmachineio/MadBoards.git", .upToNextMinor(from: "0.0.1")),
        .package(url: "https://github.com/madmachineio/MadDrivers.git", .upToNextMinor(from: "0.0.1")),
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "ReadSHT3x",
            dependencies: [
                "SwiftIO",
                "MadBoards",
                // use specific library would speed up the compile procedure
                .product(name: "SHT3x", package: "MadDrivers")
            ]),
        .testTarget(
            name: "ReadSHT3xTests",
            dependencies: ["ReadSHT3x"]),
    ]
)

3. In the file main.swift, import the SHT3x, then you could use everything in it to communicate with the sensor.

import SwiftIO
import MadBoard
import SHT3x

let i2c = I2C(Id.I2C0)
let sensor = SHT3x(i2c)

while true {
    let temperature = sensor.readCelsius()
    let humidity = sensor.readHumidity()
    print(temperature)
    print(humidity)
    sleep(ms: 1000)
}

4. If more drivers are needed, you can repeat 2 and 3 above.

Contribute

First of all, a big thanks to you for taking the time to contribute 🥰! Any corrections, enhancements and supplements are welcome!

If you want to use some sensors which is not included in the MadDrivers, you can open an issue or create a pull request from your own fork.

How can I contribute from my own fork

1. Fork the MadDrivers repository to your GitHub account by clicking the Fork button in the top right corner of this page.

2. Clone the repo to your local computer.

git clone https://github.com/YOUR-USERNAME/MadDrivers.git

3. Enter the directory you just cloned.

cd MadDrivers

4. Create a new branch feature/add_sht3x off of main for your changes.

git checkout -b feature/add_sht3x

5. Start to work on your driver and test your code using the sensor. Check the driver guide for some extra info.

6. After you implement the driver, push your changes to your repo.

git push --set-upstream origin feature/add_sht3x

7. Go to your forked repo and click the button Compare & pull request to propose your changes to the upstream repo.

8. Click the button Create pull request.

9. After your request is sent, the CI will check your PR automatically. If no error occurs and no modification is required, your request will be reviewed and merged into main branch.

To-do list

If you would like to create a new driver, below is our to-do list of sensors for your reference. Feel free to propose more sensors.

Driver guide

This part guides you through adding a new driver to this library. Take SHT3x for example.

To start with, let's have an overview of the main repository’s source tree. The MadDrivers is a Swift package. You'll find source code for all drivers, example projects, a manifest file, and other files.

• Sources: device driver code.
• Examples: simple demos for each device to get started.
• Tests: test for device drivers.
• Package.swift: package name and its content.
• Package.mmp: MadMachine project file.

├── MadDrivers
│   ├── Sources
│   │   ├── SHT3x
│   │   │   ├── SHT3x.swift
│   ├── Examples
│   │   ├── SHT3x
│   │   │   ├── ReadValues
│   ├── Tests
│   │   ├── SHT3xTests
│   ├── Package.swift
│   ├── Package.mmp
│   ├── ...

To add your driver, you will

1. create a new folder SHT3x in the folder Sources. Each folder in it matches a device.
2. create a swift file named SHT3x.swift in the folder SHT3x. This file stores the code to configure the sensor.
3. add the new target SHT3x to the file Package.swift as below.

import PackageDescription

let package = Package(
    name: "MadDrivers",
    products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "MadDrivers",
            targets: [
                "SGP30",
                "SHT3x",
                "ST7789"
                ]),
        .library(name: "SGP30", targets: ["SGP30"]),
        .library(name: "SHT3x", targets: ["SHT3x"]),
        .library(name: "ST7789", targets: ["ST7789"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(url: "https://github.com/madmachineio/SwiftIO.git", .branch("main")),
        .package(url: "https://github.com/apple/swift-numerics", from: "1.0.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "SGP30",
            dependencies: ["SwiftIO",
                           .product(name: "RealModule", package: "swift-numerics")]),
        .target(
            name: "SHT3x",
            dependencies: ["SwiftIO"]),
        .target(
            name: "ST7789",
            dependencies: ["SwiftIO"]),
    ]
)

4. write code for the sensor according to its datasheet. At the same time, you can find many drivers created by manufacturers or others as a reference.

5. in the folder Examples, create a new folder SHT3x to store demo project(s).

Info: BTW, we add tests for each sensor while writing code, which will prevent us from some typos and obvious errors. You could also skip it. If you want to have a try, one thing to note is that the SwiftIO library used for tests is from the branch mock. You need to change its version while working on tests. As for how to write tests, you could refer to SHT3xTests. It lies in supposing the values from a sensor and calculating the result your methods should produce.