Getting Started Guide¶

Follow this guide to:

Set up a command-line mJacket development environment on Ubuntu, macOS, or Windows (instructions for other Linux distributions are discussed in installation_linux)
Get the source code
Set up a project template
Build, flash, and run a sample application

Select and Update OS¶

Click the operating system you are using.

This guide covers Ubuntu version 18.04 LTS and later.

sudo apt update
sudo apt upgrade

On macOS Mojave or later, select System Preferences > Software Update. Click Update Now if necessary.

On other versions, see this Apple support topic.

Select Start > Settings > Update & Security > Windows Update. Click Check for updates and install any that are available.

Clone mJackets API¶

Next, clone the mJackets API:

git clone https://github.com/RoboJackets/mjackets-api.git

Install Dependencies¶

Next, you’ll install some host dependencies using your package manager.

Use the ubuntu-setup.sh script in the ./utilities directory to automatically install all the required dependancies:
```
cd mjackets-api
./utilities/ubuntu-setup.sh
```
Verify the version of cmake installed on your system using:
```
cmake --version
```
If it’s not version 3.13.7 or higher, follow these steps to add the Kitware third-party apt repository to get an updated version of cmake.
1. Add the Kitware signing key:
```
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
```
2. Add the Kitware apt repository for your OS release. For Ubuntu 18.04 LTS:
```
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
```
3. Then install the updated cmake with apt:
```
sudo apt update
sudo apt install cmake
```

Use the osx-setup.sh script in the ./utilities directory to automatically install all the required dependancies:
```
cd mjackets-api
./utilities/osx-setup.sh
```

These instructions must be run in a cmd.exe command prompt. The required commands differ on PowerShell.

These instructions rely on Chocolatey. If Chocolatey isn’t an option, you can install dependencies from their respective websites and ensure the command line tools are on your PATH environment variable.

|p|

Install chocolatey
Open an Administrator cmd.exe window: press the Windows key, type “cmd.exe”, right-click the result, and choose “Run as Administrator”.
Disable global confirmation to avoid having to confirm installation of individual programs:
```
choco feature enable -n allowGlobalConfirmation
```

Use choco to install dependencies:

choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install make gperf python git

Open a new cmd.exe window as a regular user to continue.

Create Template Project Repository¶

Next, install the project template into a new workspace named mjacketproject.

cd mjackets-api
./install.sh -p ~/mjacketproject
cd ~/mjacketproject

cd mjackets-api
./install.sh -p ~/mjacketproject
cd ~/mjacketproject

cd mjackets-api
./install.sh -p %HOMEPATH%\mjacketproject
cd %HOMEPATH%\mjacketproject

Board Configuration¶

If using one of the Supported Boards, then uncomment and set the BOARD variable in the top-level CMakeLists.txt to your board name to pull in the pin definitions, STM32 device, and HAL configuration for your board.

If you are using a custom board, then follow the Board Configuration Guide to specify your board’s STM32 device, pin definitions, and HAL configuration.

Configure Project Sources¶

Add the Blinky sample source code to your application by adding the below line to your top-level CMakeLists.txt:

target_add_sources(mjacketproject ${TEST_BLINKY_SOURCES})

Build the Blinky Sample¶

Note

Blinky is compatible with most, but not all, boards. If your board does not meet Blinky’s blinky-sample-requirements, then hello_world is a good alternative.

Build the blinky-sample with make build.

cd ~/mjacketproject
make build

cd ~/mjacketproject
make build

cd %HOMEPATH%\mjacketproject
make build

Flash the Sample¶

Connect your board, usually via USB or JTAG, and turn it on if there’s a power switch.

Then flash the sample using the python flasher script provided in the utilities directory. Follow the steps provided in the flashing guide to flash the firmware executable to your board using your preferred method. An example is provided below.

python flash.py -m JLINK -b ./sample.bin -c STM32F405RG

You may need to install additional host tools required by your board. An error will be printed if any required dependencies are missing.

If you’re using Blinky, the LED will start to blink.

Next Steps¶

Here are some next steps for exploring mJackets:

Check out the Application Development Guide for an in-depth guide on developing mJackets API applications.
Check out the Build System Guide for an in-depth explaination on how the build system works.
Check out the Debugging Guide for how to get debugging set up in your IDE.
Check out the Contribution Guide for information on how to contribute to the mJackets API.