artemis

A Visual Studio Code development environment for SparkFun Artemis based boards.

This project provides a starting template to develop, build, load, and debug SparkFun Artemis based boards using Visual Studio Code in conjunction with Segger J-Link. This project natively supports the Windows 10 platform and does not rely on Windows Subsystem for Linux (WSL), MinGW, etc. The batch file, build.bat, which supports building and loading from Windows is modeled after the Makefile template provided in the SparkFun Board Support Package repository.

While the current configuration supports Segger J-Link, it can be configured to support OpenOCD, etc.

The SparkFun Artemis forum is highly recommended for information and support.

In addition to providing a starting template to develop, build, load, and debug with Visual Studio Code, this project also serves as a foundation for a quadruped robot inspired by the work of Martin Triendl. While the full implementation is maintained in a seperate repository, core components are updated in this repository to provide others a starting point (or at minimum, example code). For instance, the code demonstrates how to control servos using the PCA9685 Servo Driver over I2C via the AmbiqSuiteSDK HAL transfer functions. It also demonstrates how to read data from an InvenSense ICM-20649 IMU (accel/gyro) over SPI via the same AmbiqSuiteSDK HAL transfer functions.

Dependencies

The latest version of each tool/extension should be used unless otherwise noted. During installation if the option is available to add a given tool to the system PATH environment variable please do so. This is very important for the GNU Arm Embedded Toolchain.

The following tools are required to make use of this repository:

• git
• GNU Arm Embedded Toolchain
• Segger J-Link
• Visual Studio Code

The following Visual Studio Code extensions are required:

• C/C++
• Cortex-Debug

The following Visual Studio Code extensions are recommended:

• ARM
• LinkerScript

Getting Started

Clone this repository and initialize its submodules

git clone https://github.com/0xcart/artemis.git
cd artemis
git submodule update --init --recursive

This repository includes the SparkFun copy of the AmbiqSuite SDK as a git submodule. In turn, this copy of the SDK includes the SparkFun Board Support Package repository as a git submodule. By using the --init and --recursive flags both submodules will be initialized and updated correctly.

Open the project

Launch Visual Studio Code.

Click File, Open Folder... from the main menu. Select the artemis folder and click Select Folder. You should now see the following in the Explorer view within Visual Studio Code:

Configure the Cortex-Debug Visual Studio Code extension

Highlight the Cortex-Debug extension in the Extensions view within Visual Studio Code. Click the Manage (gear) icon. Click the Extension Settings option in the displayed popup menu. A Settings document will be loaded for the extension.

Click on Edit in settings.json which will open the settings.json document. Update the settings with the following information taking care the paths for the J-Link GDB server and ARM toolchain are correct for your system configuration.

{
  "editor.wordWrapColumn": 120,
  "cortex-debug.JLinkGDBServerPath": "C:/Program Files (x86)/SEGGER/JLink/JLinkGDBServerCL.exe",
  "cortex-debug.armToolchainPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/9 2020-q2-update/bin",
  "window.zoomLevel": 0,
}

Update the c_cpp_properties.json settings in the .vscode folder

Update the compilerPath value to match your system configuration.

{
  "version": 4,
  "configurations": [
    {
      "name": "gcc-arm",
      "includePath": [
        "${workspaceFolder}/src",
        "${workspaceFolder}/AmbiqSuiteSDK/boards_sfe/artemis_thing_plus/bsp",
        "${workspaceFolder}/AmbiqSuiteSDK/utils",
        "${workspaceFolder}/AmbiqSuiteSDK/devices",
        "${workspaceFolder}/AmbiqSuiteSDK/mcu/apollo3",
        "${workspaceFolder}/AmbiqSuiteSDK/CMSIS/AmbiqMicro/Include",
        "${workspaceFolder}/AmbiqSuiteSDK/CMSIS/ARM/Include"
      ],
      "defines": [],
      "compilerPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/9 2020-q2-update/bin/arm-none-eabi-gcc.exe",
      "intelliSenseMode": "gcc-arm"
    }
  ]
}

Update the launch.json settings in the .vscode folder

Update both serverpath values to match your system configuration. Also update the cpuFrequency, swoFrequency, and device values to match your Artemis board. For most SparkFun Artemis boards the default values should be correct.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "launch",
      "type": "cortex-debug",
      "request": "launch",
      "cwd": "${workspaceRoot}",
      "servertype": "jlink",
      "serverpath": "C:/Program Files (x86)/SEGGER/JLink/JLinkGDBServerCL.exe",
      "interface": "swd",
      "swoConfig": {
        "enabled": true,
        "cpuFrequency": 48000000,
        "swoFrequency": 2000000,
        "source": "probe",
        "decoders": [
          {
            "type": "console",
            "label": "ITM",
            "port": 0,
            "encoding": "ascii"
          }
        ]
      },
      "device": "AMA3B1KK-KBR",
      "svdFile": "${workspaceRoot}/AmbiqSuiteSDK/pack/SVD/apollo3.svd",
      "executable": "${workspaceRoot}/bin/output_svl.axf",
      "runToMain": true,
    },
    {
      "name": "attach",
      "type": "cortex-debug",
      "request": "attach",
      "cwd": "${workspaceRoot}",
      "servertype": "jlink",
      "serverpath": "C:/Program Files (x86)/SEGGER/JLink/JLinkGDBServerCL.exe",
      "interface": "swd",
      "swoConfig": {
        "enabled": true,
        "cpuFrequency": 48000000,
        "swoFrequency": 2000000,
        "source": "probe",
        "decoders": [
          {
            "type": "console",
            "label": "ITM",
            "port": 0,
            "encoding": "ascii"
          }
        ]
      },
      "device": "AMA3B1KK-KBR",
      "svdFile": "${workspaceRoot}/AmbiqSuiteSDK/pack/SVD/apollo3.svd",
      "executable": "${workspaceRoot}/bin/output_svl.axf",
    }
  ]
}

Update build.bat

Several parameters in build.bat must be verified and/or updated.

The first set of parameters are associated with your Artemis board. Please update the values for these parameters to match your boards attributes. The default values found in build.bat are for the Artemis Thing Plus. If you're using this board then no modifications should be necessary. The value for BLD_BOARD should match one of the folders found in artemis/AmbiqSuiteSDK/boards_sfe.

• BLD_BOARD=artemis_thing_plus
• BLD_PART=APOLLO3
• BLD_MCU=apollo3
• BLD_CPU=cortex-m4
• BLD_FPU=fpv4-sp-d16
• BLD_FABI=hard

The second set of parameters are associated with communications to your board. Please update these values as necessary. A baud rate of 921600bps is correct for the SparkFun Variable Loader (SVL).

• BLD_BAUD=921600
• BLD_PORT=COM4

In the future, when you're ready to add additional source files, libraries, etc., you'll need to update the following parameters:

• BLD_INCLUDE=
• BLD_SOURCE=
• BLD_LIBRARY=

Build, Load, Debug, and Clean

Build

Press F1. This will display a popup menu listing all commands. Select Tasks: Run Build Task from the list of commands to display the build task. Alternatively you can press Ctrl + Shift + B to reach the same build task.

To build the project select svl binary. You should see the following printed to the console:

Making    'bin' directory
Compiling 'src/artemis_startup.c'
Compiling 'src/artemis_main.c'
Compiling 'src/artemis_mcu.c'
Compiling 'src/artemis_debug.c'
Compiling 'src/artemis_watchdog.c'
Compiling 'src/artemis_time.c'
Compiling 'src/artemis_scheduler.c'
Compiling 'src/artemis_task.c'
Compiling 'src/artemis_core.c'
Compiling 'src/artemis_led.c'
Compiling 'src/artemis_iom.c'
Compiling 'src/artemis_i2c.c'
Compiling 'src/artemis_spi.c'
Compiling 'src/artemis_stream.c'
Compiling 'src/artemis_pca9685.c'
Compiling 'src/artemis_servo.c'
Compiling 'src/artemis_icm20649.c'
Compiling 'src/artemis_imu.c'
Compiling 'src/artemis_gpio.c'
Compiling 'src/artemis_uart.c'
Compiling 'AmbiqSuiteSDK/devices/am_devices_led.c'
Compiling 'AmbiqSuiteSDK/utils/am_util_delay.c'
Compiling 'AmbiqSuiteSDK/utils/am_util_stdio.c'
Linking   'bin/output_svl.axf' with script 'AmbiqSuiteSDK/boards_sfe/common/tools_sfe/templates/asb_svl_linker.ld'
Creating  'bin/output_svl.lst'
Creating  'bin/output_svl.bin'

=== BUILD SUCCESSFUL ===

A bin directory is created containing the following list of output files:

• am_devices_led.o
• am_util_delay.o
• am_util_stdio.o
• artemis_core.o
• artemis_debug.o
• artemis_gpio.o
• artemis_i2c.o
• artemis_icm20649.o
• artemis_imu.o
• artemis_iom.o
• artemis_le