Blink

Let's first come to an easy beginner project - blink the onboard LED. The LED will be on and off per second. It is always the first try when you begin to program the microcontrollers, like a hello world project.

What you need

• SwiftIO Micro (or SwiftIO board)

info

All projects in the section General will use the SwiftIO Micro as an example. You can also use the SwiftIO board instead. If so, you need to change the board type and code (if necessary) accordingly.

Circuit

For this project, you only need the board. There is a built-in RGB LED on the board as shown in the image above. You can control it using the methods in DigitalOut class.

Just plug the board into your computer with a USB cable to download your code.

Example code

It's time for the code. Let's see how it works.

Open the project Blink in the folder MadExamples/Examples/GettingStarted if you downloaded the all examples.

Blink.swift

// Turn on and off the onboard LED continuously.

// Import the library to enable the relevant classes and functions.
import SwiftIO
import MadBoard

@main
public struct Blink {
    public static func main() {
        // Initialize the onboard green LED with other parameters set to default.
        let green = DigitalOut(Id.GREEN)

        // Blink the LED over and over again.
        while true {
            // Apply a high voltage and turn off the LED.
            green.write(true)
            // Keep the light off for a minute.
            sleep(ms: 1000)

            // Apply a low voltage and turn on the LED.
            green.write(false)
            // Keep the light on for a minute.
            sleep(ms: 1000)
        }
    }
}

Background

Digital signal

The digital signal usually has two states, whose value is either 1 or 0. In our cases, 1 represents 3.3V and 0 represents 0V. There are also other ways to express the same meaning: high or low, true or false. Now you will control the output voltage to turn on or off the LED.

LED

The LED, or light-emitting diode, is one kind of diode. It has a positive leg (anode) and a negative leg (cathode). The long leg is positive, and the short leg is negative. The current could only flow in one direction, from positive to negative, so you should connect the positive to the current source. Only when you connect it in the right direction, the current could flow.

There are two ways to connect the LED:

1. Connect the LED to a digital pin and ground (GND), as shown in the upper left corner. The current always flows from high to low voltage.

   • If the pin outputs a high voltage, the current flows from that pin to GND, hence the LED will be on.
   • On the contrary, if it outputs a low voltage, there's no current and the LED turns off.

2. Connect the LED to the power (Vcc) and a digital pin, as shown in the lower left corner. This is how the onboard LED works. The diagram on the right shows its circuit connection.

   • If the pin outputs a high voltage, there is no voltage difference between the two ends of the LED, so the LED is off.
   • When the pin outputs a low voltage, the current can flow from the power to that pin, and the LED will be on.

You can find an LED beside the download button on your board. It is a different type for easier soldering. This RGB LED has three colors: red, green and blue. As you download the code, it serves as a status indicator. Besides, you can also control its color and state by setting the output voltage.

• You can light any one of them, which means the red, green, or blue LED will be turned on.
• You can also turn on two of them. For example, if you choose red and blue, you can notice the light appears magenta.
• If all three LEDs are on, the light becomes white.

Code analysis

import SwiftIO
import MadBoard

SwiftIO consists of all the functionalities to control your board. All programs must first reference it to use everything in it, like classes and functions.

MadBoard defines the corresponding pin id of the different boards.

@main
public struct Blink {
    public static func main() {
    
    }
}

@main signifies the top-level entry point of your program. It comes with a static method main(). The program will execute the code there. For convenience, you could put your code within main() as the example code.

let green = DigitalOut(Id.GREEN)

Before you set a specific pin, you need to initialize it. let is a keyword for Swift language to declare constants. You will often use it to assign a name to the pin for easier reference later.

This statement is to create an instance for DigitalOut class and initialize that pin. So you need to indicate its id. All ids are in an enumeration, and the built-in RGB LEDs use the id RED, GREEN, or BLUE, thus the id of blue LED here is written as Id.GREEN using dot syntax.

while true {

}

In the dead loop while true, all code in the brackets will run over and over again unless you power off the board.

green.write(true)

The method write(_:) is used to set the pin to output high or low voltage. Its parameter is a boolean type: true or false: true corresponds to a high level (3.3V) and false corresponds to a low level (0V). And as mentioned above, you need to set a low voltage to turn on the LED.

sleep(ms: 1000)

The function sleep(ms:) will stop the microcontroller's work for a specified period. It needs a period in milliseconds as its parameter. It is a global function in the library, so you can directly use it in your code.

In the loop, the pin outputs high voltage and then sleeps for 1 second. So in the first 1s, there is always a high voltage. Similarly, in the next 1s, the pin outputs low voltage.

Reference

DigitalOut - set whether the pin outputs a high or low voltage.

• init(_:mode:value:) - initialize the digital output pin. The first parameter needs the id. You can refer to the corresponding Id enumeration. The parameters mode and value already have their default value.

• write(_:) - set the specified pin to output high or low voltage. Its parameter is a boolean type. true corresponds to a high level, and false corresponds to a low level.

sleep(ms:) - suspend the microcontroller's work and thus make the current state last for a specified time, measured in milliseconds.

MadBoard - find the corresponding pin id of your board.