Skip to content

Latest commit

 

History

History
417 lines (297 loc) · 16 KB

README.md

File metadata and controls

417 lines (297 loc) · 16 KB
Raw

Introduction

MCU+ SDK is a software development package designed for usage with Sitara MCU+ class of devices from Texas Instruments. These devices currently include

MCU+ SDK is designed with user experience and simplicity in mind. The SDK includes out-of-box application examples and peripheral usage examples to help users hit the ground running.

Features

  • Out of Box peripheral and application Examples

    • Peripheral Level Examples: UART, ADC, I2C, SPI etc.
    • Application Level Examples: Motor Drives, Industrial Communications etc.

  • Protocol stacks and middleware

    • TinyUSB
    • LwIP
    • Various Industrial Protocol Stacks
    • FreeRTOS-FAT

  • Drivers and Hardware Abstraction Layer

    • Board peripheral drivers - Flash, EEPROM, LED etc.
    • SoC peripheral drivers - I2C, SPI, OSPI, ADC etc.

  • Industrial protocol firmware

    • ICCSG, ICSSM etc.

  • OS kernel layer

    • Driver Porting Layer(DPL) which acts as an abstraction layer between driver and OS
    • Out of Box Support for
      • FreeRTOS
      • Baremetal i.e NO RTOS builds

Overview

Software Block Diagram

MCU+ SDK source comprises of multiple repositories with the current repository at it's core. To build the SDK successfully, there are other repositories that need to be cloned and are listed below:

We use the repo tool to clone and manage multiple repositories. To setup the repo tool, navigate to repo tool setup section.

Prebuilt SDK installers for specific devices are available at below links. Please note that installers are packaged specific to each device to reduce size.

Learn

TI has an amazing collection of tutorials on MCU+ Academy to help you get started.

Usage

Prerequisites

Supported HOST environments

  • Windows 10 64bit
  • Ubuntu 18.04 64bit

Clone and build from GIT

West tool Setup

MCU+ SDK has multiple components (in multiple repositories) and dependencies (like compiler, CCS and other tools). We utilize West tool from the Zephyr project to manage these multiple repositories. West serves as an alternative to Google's repo tool. We are transitioning to West because the repo tool does not support the Windows native shell. For those using West to clone the repository, the repo tool setup is unnecessary. Follow the steps below to set up the West tool:

Make sure python3 is installed and is in your OS path.

Do the following in terminal

  • Linux:

    pip3 install --user -U west

  • Windows and macOS

    pip3 install -U west

If you are using a network proxy, include the --proxy={your_network_proxy} option in the pip installation command.

Cloning The Repositories - West

To clone the repositories using West tool, do below in your workarea folder:

Note that the components you clone may vary depending on the SoC you are working with. Therefore, please select the manifest folder that corresponds to the SoC you are interested in. For example, {device}/dev.yml. We are providing the link for cloning dependent repositories for all devices in the /dev.yml file below.

west init -m https://github.com/TexasInstruments/mcupsdk-manifests.git --mr mcupsdk_west --mf all/dev.yml

After the west is initialized, do a

west update

This should clone all the repositories required for MCU+ SDK development. Now proceed to Download and Install dependencies section

Repo Tool Setup (Deprecated in the next release)

MCU+ SDK has multiple components (in multiple repositories) and dependencies (like compiler, CCS and other tools). We use repo tool from Google to manage these multiple repositories. Currently there is no support for native windows shells like CMD or Powershell. West tool is recommeded for other platforms. Windows users can rely on Git Bash for the repo setup. Follow the below mentioned steps to setup repo tool:

Make sure python3 is installed and is in your OS path.

  • Linux: Do the following in terminal

    curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
echo "PATH=$HOME/bin:$PATH" >> ~/.bashrc
source ~/.bashrc

  • Git-Bash (Windows) Make sure that python 3 is callable as python from CMD. Do below in Git-Bash

    mkdir -p /c/ti
curl https://storage.googleapis.com/git-repo-downloads/repo > /c/ti/repo
echo "alias repo=\"winpty python /c/ti/repo\"" >> ~/.bashrc
source ~/.bashrc

Cloning The Repositories - Repo (Deprecated in the next release)

To clone the repositories using repo tool, do below in your workarea folder:

Note that depending on the SoC you're working with, the components you clone might be slightly different. So please choose the manifest folder according to the SoC of your interest. For example, we are showing for am263x below.

repo init -u https://github.com/TexasInstruments/mcupsdk-manifests.git -m am263x/dev.xml -b main

Note that repo uses symbolic links. So if you're on Windows and do not have permissions to create symbolic links, the above command might fail for you. So you can either enable them (refer this link) or use the experimental worktree feature of repo. To do this, initialize the repo like so:

repo init --worktree -u https://github.com/TexasInstruments/mcupsdk-manifests.git -m am263x/dev.xml -b main

After the repo is initialized, do a

repo sync

This should clone all the repositories required for MCU+ SDK development. Now download and install the dependencies.

Downloading And Installing Dependencies

Note that the dependencies are also soc specific, here we take an example of am263x. You can replace that with the SoC of your choice like the repo init step.

To download and install dependencies in linux, follow the below steps:

Run the following from the same location where you have mcu_plus_sdk and mcupsdk_setup folders.

./mcupsdk_setup/am263x/download_components.sh

This will install all the required dependencies including Code Composer Studio (CCS). The script assumes that mcu_plus_sdk folder is in the same location from where you have invoked the script, and that dependencies are installed into ${HOME}/ti location. If these defaults don't work for you, please pass these as arguments to the script like

./mcupsdk_setup/am263x/download_components.sh --install_dir=/path/to/tools

OR

./mcupsdk_setup/am263x/download_components.sh --mcu_plus_sdk_folder=/path/to/mcu_plus_sdk/folder

and so on. For a complete list of arguments you can pass to the script, please run

./mcupsdk_setup/am263x/download_components.sh -h

In windows the dependencies has to be manually installed. Given below are the steps:

  1. Download and install Code Composer Studio v12.8.1 from here

    • Install at default folder, C:\ti

  2. Download and install SysConfig 1.21.2 from here

    • Install at default folder, C:/ti

  3. Download and install GCC for Cortex A53 and ARM R5 from below link (only needed for AM64x developers)

  4. Download and install Node.js v12.18.4 LTS

  • Go to the NodeJS Website and use the installer to download and install v12.18.4 of node. Install in the default directory.
  • After successful installation, run an npm ci inside the mcu_plus_sdk folder like so: 
    $ cd mcu_plus_sdk/
$ npm ci
$ cd ../
    This should install the node packages required for the SDK.
  1. Download and install doxygen,
    • Tested with 1.8.20
      • Download the correct version of doxygen for windows from here
      • Install and add the install path, typically, C:/Program Files/doxygen/bin to your windows PATH
    • Test by doing below on the command prompt 
      $ doxygen -v
1.8.20 (<commit SHA-ID>)

Installing OpenSSL

Some of the SDK signing scripts are dependent on OpenSSL. Current signing scripts of SDK support both v1.1.1 and v3 of OpenSSL. With am263x, am263px, am273x OpenSSL v3 is recommended as v1.1.1 has reached END OF LIFE.

In Windows,

  • Download OpenSSL v1.1.1 or v3 from here
  • You can install the "light" version which is smaller download size
  • Install to default path, which is C:/Program Files/OpenSSL-Win64/
  • When prompted select option to install binaries to /bin folder of installed path instead of Windows system path.
  • Add path to OpenSSL, to your environment "Path" variable in windows
    • C:\Program Files\OpenSSL-Win64\bin

In Linux,

  • There is a chance that OpenSSL is already installed. If not, here are the steps:

  • If you have Ubuntu 22.04, do below in Linux Ubuntu shell to install openssl -$ sudo apt install openssl

    Make sure that v1.1.1 or v3 version of OpenSSL is installed. The v1.1.1 or v3 packages are also available here. The packages required are openssl, libssl and libssl-dev

Test openssl version by running openssl version on a command prompt and make sure there is no error. Example output is shown below,

  C:\> openssl version
  OpenSSL 1.1.1k  25 Mar 2021

OR

    ~/workarea/mcu_plus_sdk$ openssl version
    OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)

Now that the dependencies are installed, you can start the repositories with a default branch dev by doing below:

repo start dev --all

NOTE

  • In Linux, you will need to run $HOME/ti/ccs{version}/ccs/install_scripts/install_drivers.sh script for setting COM port accesses correctly. Also add your user to groups tty and dialout. You can do

    sudo adduser $USER tty
sudo adduser $USER dialout

  • Please use the industrial communication libraries from the sdk installer due licensing restrictions.

Building the SDK

Basic Building With Makefiles

NOTE

  • Use gmake in windows, add path to gmake present in CCS at C:\ti\ccsxxxx\ccs\utils\bin to your windows PATH. We have used make in below instructions.
  • Unless mentioned otherwise, all below commands are invoked from root folder of the "mcu_plus_sdk" repository.
  • Current supported device names are am64x, am243x, am263x, am273x and awr294x
  • Pass one of these values to "DEVICE="
  • You can also build components (examples, tests or libraries) in release or debug profiles. To do this pass one of these values to "PROFILE="

  1. Run the following command to create makefiles, this step is optional since this is invoked as part of other steps as well,

    make gen-buildfiles DEVICE=am263x

  2. To see all granular build options, run

    make -s help DEVICE=am263x

    This should show you commands to build specific libraries, examples or tests.

  3. Make sure to build the libraries before attempting to build an example. For example, to build a Hello World example for AM263x, run the following:

    make -s -j4 libs DEVICE=am263x PROFILE=debug

    Once the library build is complete, to build the example run:

    make -s -C examples/hello_world/am263x-cc/r5fss0-0_nortos/ti-arm-clang all PROFILE=debug

  4. Following are the commands to build all libraries and all examples. Valid PROFILE's are "release" or "debug"

    make -s -j4 clean DEVICE=am263x PROFILE=debug
make -s -j4 all   DEVICE=am263x PROFILE=debug

More information on SDK usage

For more details on SDK usage, please refer to the SDK userguide. User guides contain information on

  • Building the SDK
  • EVM setup,
  • CCS Setup, loading and running examples
  • Flashing the EVM
  • SBL, ROV and much more.

Note that userguides are specific to a particular device. The links for all the supported devices are given below.

The documentation can also be generated as mentioned in the below section.

Generate Documentation

  • Goto mcu_plus_sdk and type below to build the documentation for the device of interest

    make docs DEVICE=am263x

  • Browse API guide by opening below file for a DEVICE of interest

    README_FIRST_*.html

  • Also note that code snippets added to “docs_src\docs\api_guide\doxy_samples” is valid code that can compile. Above command also compiles the code snippets.

Contributing to the project

This project is currently not accepting contributions. Coming Soon!