title	author	email
Lab 1: Worksheet	Dan Goldsmith	aa9863@coventry.ac.uk

The Setup

Creating the Project

Our first task is to create a new project in VS Code for Platform IO. (Figure 1)

We need to know:

The target hardware that we are aiming to develop for.
Any supporting middleware that we are expecting to use.

This means our Settings are: (Figure 2)

Project Name: Something Sensible
Board The Project board we are using (STM32F4)
Framework mbed

$Initial Settings \label{fig:setup}$

The new project opens and is now visible in the Explorer on the Left Hand side of the window. (Figure 3)

Opening the code for editing

All of the code we write will have an entrypoint this is code in a specified "block" that is run by default when the program starts.

Like the traditional C/C++ programs, the entrypoint for the embedded systems we are developing is the main() function. Which by default is in the main.cpp source file.

Note: Like traditional C, it doesn't really matter what the source file that contains main is called. However, for sanity I would recommend keeping it as main.cpp.

We can click on the file in the explorer to open it.

\clearpage

The Code

Template Walk through

First lets take a walk through through the code that we have as a template. You can see its very similar to the C we are used to.

#include <mbed.h>

int main() {

  // put your setup code here, to run once:

  while(1) {
    // put your main code here, to run repeatedly:
  }
}

#include <mbed.h> Include the MBED libraries
int main(){} Main function, our entrypoint to the program. This function is called once when the program starts. We can setup variables and initialised devices ready for the mainloop (or threads) to deal with.
while(1) The Main loop within the function. This is our event loop, and will run continuously while power is applied to the device. Note that in this example we are not making use of more advanced scheduling functionality offered by the ROTS elements of MBED

Setting up the LED pin

Our first task is to configure the board so that the Pins connected to the LED is configured for output. For this we can use the DigitalOut function

https://os.mbed.com/docs/mbed-os/v5.11/apis/digitalout.html

The Following code initialises the digital pin on LED1 to output mode. And names it ledOne

//Setup LED 
DigitalOut ledOne(LED1);

NOTE. We could put this in the Main Function. However, this would limit the scope of the DigitalOut object to just within main. While Globals can be a "Bad Thing(TM)" in traditional coding, its unlikely the function of a pin will change and several sections of the code may need access to the same item.

Writing the main loop.

We now need to put together the main loop. This will run sequentially for ever.

Our basic Pseudo code would be

Turn LED on
Wait for a set amount of time
Turn LED off
Wait for a set amount of time

This translates to the following MBED code:

  while(1) {
    // Turn LED on
    ledOne = 1;
	// Sleep
    wait(0.5);
	// Turn LED off
    ledOne = 0;
	// Sleep
    wait(0.5);
  }

Compiling and Uploading the Code to the Target Board

Compiling the code

Like all C based programs, the code needs to be compiled before it can be uploaded to the board.

Compile (or Build) is the button that looks like an tick on the toolbar.

Note: The first time the code compiles can take a while, as platformIO download the relevant toolchain and libraries. You WILL need internet access for this stage

The compile process is shown in the Terminal window

Debugging compile issues

If we have made an error in the code, the terminal window should display some useful (although its based on GCC so your mileage may vary) error messages.

For example, here we have missed a semicolon (frequent for us Python users) in the code. As usual the error message is on the line where the error was encountered, its usually the line before.

PLATFORM: ST STM32 > ST Nucleo F746ZG
HARDWARE: STM32F746ZGT6 216MHz 320KB RAM (1MB Flash)
DEBUG: CURRENT(stlink) ON-BOARD(stlink) EXTERNAL(blackmagic, jlink)
Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF MODES: FINDER(chain) COMPATIBILITY(soft)
Collected 41 compatible libraries
Scanning dependencies...
No dependencies
Compiling .pioenvs/nucleo_f746zg/src/main.o
src/main.cpp: In function 'int main()':
src/main.cpp:15:5: error: expected ';' before 'ledOne'
ledOne = 0;
^~~~~~
*** [.pioenvs/nucleo_f746zg/src/main.o] Error 1
========== [ERROR] Took 2.22 seconds ==========
The terminal process terminated with exit code: 1

Terminal will be reused by tasks, press any key to close it.

Digression: Checking the Code in the MBED online simulator

Before we upload the code, we can try the program in the online MBED simulator.

http://ec2-52-211-146-247.eu-west-1.compute.amazonaws.com:7829/

Copy and paste the code and hit the run button.

Uploading the code to the Board

The final stage of the development process is to upload the code to the target board.

Connect the board over USB
- NOTE: There are two USB sockets on the board. We need the USB host one (near the microphone)
Click the upload (arrow) button on the toolbar

Hopefully everything will work OK and one LED will be flashing.

Uploading the Code to the Board (Altherative)

Depending on your setup, the automated uploading will not work. A good sign that this will appen is if teh board comes up as a USB device when you plug it in to the PC.

In this case you need to copy the .bin file from the Build (~/Documents/PlatformIo/Pojects//.pio/build//firmware.bin) file across to te USB drive that represents the device, and press reset.

Note the .pio file may be hidden, you can see it via the options.

\clearpage

Basic Debugging

Basic Debugging with Printf

If the program isn't working as expected, we can perform some basic debugging using print statements.

For example:

int main(){
  printf("Starting\n");
  while(1){
    printf("Tick.\n");
    ledOne = 1;
    wait(0.5);
    ledOne = 0;
    wait(0.5);
    }
  }

If we use the serial monitor. (Looks like a plug on the toolbar) we can see the print output from the device.

Your Turn

The target board has 4 LEDs available to it. Modify the demo code to flash each of the LED'S

Together
In a Sequence

Try to make use of both the Simulator to check the code you have developed, and to upload to one of the target boards.

KPIT_MBED_worksheet/Topic1/PlatformIO_Worksheet.md