Software setup

You can install the software on your own machine before the course even starts (and before you have your discoboard). You only have to do this setup stuff once per computer.

The Integrated Development Environment (IDE) we use in COMP2300/6300 is Visual Studio Code (we’ll usually call it VSCode for short). VSCode is a generic text editor, which means that it’s really good at editing text, but doesn’t care too much what that text is/represents. However, VSCode also allows people to write “extensions” to help VSCode write & run code for different programming languages.

One such extension is called PlatformIO, which is an “an open source ecosystem1 for IoT (Internet of Things) development”.

We’ll only be dealing with one specific “board” (your stm32 l476g discoboard) in this course, so we won’t use all of the PlatformIO functionality. Still, it provides the compiler, assembler and other important components for writing & running code on your discoboard. You don’t have to master everything straight away, we’ll step you through it in the labs (so make sure you attend all the labs!).

Installation

If you’re on one of the CSIT Ubuntu lab machines, then most of this is already done, although if it’s the first time you’ve ever used VSCode in the CSIT labs then you’ll still have to install the VSCode extensions—jump to step 3.

To set this all up on a new machine (e.g. your own laptop) here are the steps:

  1. read the COMP2300/6300 own machine policy

  2. download & install VSCode (works on macOS, Linux & Windows)

  3. open VSCode, open the Extensions view

  4. search for and install the COMP2300 extension (anucecsit.comp2300-extension-pack)

  5. reload the VSCode window (using the command palette)

After you finish these steps, VSCode will say that it’s “Installing PlatformIO Core”. Wait until it finishes (this might take several minutes, depending on your connection & computer) then wait for the prompt to reload the window again. Be patient—if you refresh the window before it finishes it cancels the install process and you have to start again!

Using VSCode & PlatformIO

VSCode has pretty good documentation, and the lab material will link to specific parts of it where appropriate. However, understanding your tools is really important, so take the time to read through the documentation and get to know the features of VSCode. It’ll make your life easier in the end, even if there’s a learning curve at the start.

Once you’ve got VSCode & the necessary plugins installed (and you’ve got your discoboard) you’re able to write and run your first program. That’s what lab 1 is all about—so head to that page and give it a try.

Troubleshooting

Here’s a list of issues you might come across, depending on the specific details of your machine. As always, be careful with copy-pasting random code you found on the internet (even in a university course!), and try to understand the problem first before you try the solutions listed.

If there are new problems which come up often enough on Piazza I’ll add them here.

Linux

Device permission issues

On some Linux machines you might have read/write permission issues in connecting to your discoboard. As a result, PlatformIO fails to upload (pio run --target upload) with the following error message:

Couldn't find any ST-Link/V2 devices

This problem can be solved by with the following commands:

#!/bin/sh

sudo sh -c 'cat > /etc/udev/rules.d/49-stm32.rules' <<EOF
# 0483:374b - STM32F4 Dsicovery in USB Serial Mode (CN5)
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", ENV{MTP_NO_PROBE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
KERNEL=="ttyACM*", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"

# 0483:df11 - STM32F4 Discovery in DFU mode (CN5)
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"
EOF

sudo udevadm control --reload-rules

echo "Unplug and replug your device to activate the new rules."

For your convenience, here’s a script which does it all for you.

Note: the product ID is found by doing:

dmesg | grep 'New USB device found, idVendor=0483'
[195436.094414] usb 1-1.3: New USB device found, idVendor=0483, idProduct=374b

This should be the STM32L476 Discovery board product number.

Further reading:

Windows

On Windows you will need install ST-Link Debug Driver before Windows will connect to the discoboard. If you don’t, you’ll get an error like this:

WARN src\usb.c: Couldn't find any ST-Link/V2 devices *** [upload] Error -1

You can get the ST-Link driver here. Just unzip it and follow the instruction in readme.txt.

Package manager IO error

You might see the following error:

PackageManager: Installing tool-stm32duino @ ~1.0.0
Downloading [###---------------------------------] 10%
Error: Please read http://bit.ly/package-manager-ioerror
Warning! Package Mirror: [Errno 0] Error
Looking for another mirror...
Downloading [------------------------------------] 1%
Error: Please read http://bit.ly/package-manager-ioerror
Warning! Package Mirror: [Errno 0] Error
Looking for another mirror...
Error: Could not install 'tool-stm32duino' with version requirements '~1.0.0' for your system 'windows_amd64'.

Please try this solution -> http://bit.ly/faq-package-manager

You should probably try the linked solution

Disappearing st-util.exe, Possible antivirus (Avast) issue

We have encountered some issue where the st-util.exe file is being removed, I suspect this is some strange interaction with Avast but am not 100% sure, so if you have errors mentioning st-util, it is probably a good idea to check that the file is still there.

Navigate to: C:\Users"your name”\.platformio\packages\tool-stlink

is the st-util.exe file missing? If not your issue is elsewhere, but if it is missing, go back up one folder to ‘packages’ and delete the ‘tool-stlink’ folder.

After you’ve done that, run the upload command again to redownload the file (this may need to be done from command line, if you need to add platformio to your path check the field below).

If you still have issues after this, consider disabling your antivirus or changing to a different provider.

Adding platformio to windows path

  1. Open a file explorer
  2. right click This PC and select properties
  3. in the new window select Advanced system settings on the left
  4. select Environment Variables…
  5. under System variable select Path and click edit
  6. click New
  7. enter the location of your platformio Scripts file, it should look something like this: C:\Users"your name”\.platformio\penv\Scripts
  8. Keep clicking Ok until you get back to the System window.

Platformio commands should now work in command prompt.

  1. The ecosystem thing means that PlatformIO isn’t just for writing a specific program on a specific board with a specific “framework”. You can read more about it in the documentaion if you’re interested. 

Updated:  19 Feb 2018/ Responsible Officer:  Head of School/ Page Contact:  Ben Swift