PlatformIO_Worksheet.md

---
title: 'Lab 1:  Worksheet'
author: 'Dan Goldsmith'
email: '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)

![Creating a new project](Images/Lab1/NewProject.png)

We need to know:
 
  1. The target hardware that we are aiming to develop for.
  1. 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}](Images/Lab1/ProjectSettings.png)

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

![Workspace Explorer](Images/Lab1/Workspace.png)

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

![Open a File for Editing](Images/Lab1/EditMain.png)

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

~~~ c
#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

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

This translates to the following MBED code:

~~~ c
  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.

![Toolbar](Images/Lab1/Toolbar.png)

*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

![Terminal Window](Images/Lab1/Terminal.png)

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

~~~term
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.

 1. Connect the board over USB 
    - NOTE: There are two USB sockets on the board.  We need the USB host one (near the microphone)
 1. 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/<name>/.pio/build/<board>/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.

![File Location](Images/int1.png)


\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:

~~~c
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.