Skip to content

Latest commit

 

History

History
442 lines (393 loc) · 13.8 KB

README.md

File metadata and controls

442 lines (393 loc) · 13.8 KB
Raw

MadDrivers

build test codecov Discord twitter

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.

Type Device Communication
Accelerometer ADXL345 I2C/SPI
LIS3DH I2C/SPI
Color AS7341 I2C
TCS34725 I2C
VEML6040 I2C
DAC MCP4725 I2C
Dispaly
 IS31FL3731 I2C
LCD1602 I2C
ST7789 SPI
Distance
 HCSR04 GPIO
VL53L0x I2C
Gas
 BME680 I2C/SPI
SGP30 I2C
Gesture APDS9960 I2C
Gyroscope BMI160 I2C/SPI
MPU6050 I2C
Touch MPR121 I2C
Light BH1750 I2C
LTR390 I2C
TSL2591 I2C
VEML7700 I2C
Magnetometer MAG3110 I2C
MLX90393 I2C/SPI
Pressure BMP280 I2C/SPI
MPL3115A2 I2C
MS5611 I2C/SPI
RTC DS3231 I2C
PCF8523 I2C
PCF8563 I2C
Temperature & Humidity AHTx0 I2C
ADT7410 I2C
DHTxx GPIO
HTU21D I2C
MAX6675 SPI
MCP9808 I2C
SHT3x I2C
TMP102 I2C
Thermal AMG88xx I2C
Ultraviolet VEML6070 I2C
Wi-Fi ESP32 UART

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.9
// 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", branch: "main"),
        .package(url: "https://github.com/madmachineio/MadBoards.git", branch: "main"),
        .package(url: "https://github.com/madmachineio/MadDrivers.git", branch: "main"),
    ],
    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.
        .executableTarget(
            name: "ReadSHT3x",
            dependencies: [
                "SwiftIO",
                "MadBoards",
                // use specific library would speed up the compile procedure
                .product(name: "SHT3x", package: "MadDrivers")
            ]),
        .testTarget(
            name: "ReadSHT3xTests",
            dependencies: ["ReadSHT3x"]),
    ]
)
  1. 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)
}
  1. 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
  1. Enter the directory you just cloned.
cd MadDrivers
  1. Create a new branch feature/add_sht3x off of main for your changes.
git checkout -b feature/add_sht3x

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

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

git push --set-upstream origin feature/add_sht3x

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

  2. Click the button Create pull request.

  3. 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.

Type Sensors Communication
Temperature/humidity HTS221 I2C/SPI
Temperature/humidity SI7021 I2C
Pressure/Temperature MPL115A2 I2C
Temperature/Humidity/Pressure BME280 I2C/SPI
Pressure BMP085/BMP180 I2C
Pressure BMP388 I2C/SPI
Air quality CCS811 I2C
CO2 SCD4X I2C
IR Thermal Camera MLX90640 I2C
UV/IR/ambient light SI1145 I2C
Current/power monitor INA260 I2C
RF Transceiver NRF24L01 SPI
Absolute-orientation BNO055 I2C/UART
GPS MT3339 I2C/SPI/UART
Magnetic HMC5883 I2C
Gyroscope L3GD20 I2C/SPI
Magnetometer LIS2MDL I2C/SPI
Accelerometer/magnetometer LSM303 I2C
Accelerometer/gyroscope LSM6DS I2C/SPI
Accelerometer/magnetometer/gyroscope LSM9DS I2C/SPI
4-digit 7-segment display TM1637 Digital

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.
// swift-tools-version: 5.9
// The swift-tools-version declares the minimum version of Swift required to build this package.
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"]),
    ]
)

  1. 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.

  2. 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.