Add a board configuration file

This section requires the embedXcode+ edition.

With the embedXcode+ edition, you can easily create and customise a board configuration file for a new board.

You only need to define its settings and optionally a specific programmer.

The specific board configuration file My Board can also be added to the templates so it'll appear when creating a new project.

Create a configuration file for a new board

To add a configuration file for a new board,

  • Call the menu File > New > New File... or press Cmd+N.

  • Select the macOS option.

  • Scroll down to the embedXcode+ group.

  • Select Board Configuration Settings File.

The Board Configuration Settings File allows to define the settings for a new board, including a specific programmer.

  • Type in the Name of the new board.

  • Select Default for the Wiring / Arduino framework, or

  • Click on Next.

Define a new board for the Wiring / Arduino framework

When Default is selected, the new Board Configuration Settings File comes with an example for the Wiring / Arduino framework.

//
//  newBoard.xcconfig 
//  Board config file
//  ----------------------------------
//  Developed with embedXcode
//
//  Project     embed1
//
//  Created by  Rei Vilo on sept. 30, 2017
//  Copyright   (c) 2017 http://embeddedcomputing.weebly.com
//  Licence     <#Licence#>
//
// Last update: 05 Mar 2014 release 138

// Board identifier
// See Boards.txt for <tag>.name=Arduino Uno (16 MHz)
//
BOARD_TAG  = uno

// Port (optional)
// most common are /dev/tty.usbserial*, /dev/tty.usbmodem* or /dev/tty.uart*
//
BOARD_PORT = /dev/tty.usbmodem*

// References for Xcode code-sense
// See Boards.txt for <tag>.build.mcu=<GCC_PREPROCESSOR_DEFINITIONS>
//
GCC_PREPROCESSOR_DEFINITIONS = __AVR_ATmega328P__ ARDUINO

// Specify the full path and name of the application
// with /Contents/Java/** after
//
APPLICATIONS_PATH = /Applications
HEADER_SEARCH_PATHS = $HOME/Library/Arduino15/packages/arduino/hardware/avr/** $(APPLICATIONS_PATH)/Arduino.app/Contents/Java/hardware/arduino/avr/**

// Maximum RAM size in bytes
// given by <tag>.upload.maximum_ram_size in boards.txt for Maple and Teensy
// given by <tag>.upload.maximum_data_size in boards.txt for Arduino 1.5.x
//
MAX_RAM_SIZE = 2048

Set the board tag

Specify the following variables:

  • BOARD_TAG is the unique identifier of the board, found in the boards.txt file.
BOARD_TAG  = uno
  • Indexed BOARD_TAG, like BOARD_TAG1 BOARD_TAG2 ..., are sometimes required to ensure compatibility between old and new identifiers, or to complement the initial BOARD_TAG.
BOARD_TAG1 = mega
BOARD_TAG2 = mega.menu.cpu.atmega2560

Set the serial port

  • BOARD_PORT defines the USB port to be used.
BOARD_PORT = /dev/tty.usbmodem*

This parameter is optional. To know the name of the USB port, proceed as follow:

  • Open the Terminal window,

  • Plug the board,

  • Launch the command ls /dev/tty.usb*.

$ ls /dev/tty.usb*
/dev/tty.usbmodem0E100631

  • Read the answer, here /dev/tty.usbmodem0E100631.

  • Change the value of BOARD_PORT accordingly.

BOARD_PORT = /dev/tty.usbmodem*

The generic character * allows other values for the port, for example /dev/tty.usbmodem0E100641.

  • DELAY_BEFORE_SERIAL defines a delay in seconds before opening the Console.
DELAY_BEFORE_SERIAL = 5

If previous versions, DELAY_PRE_SERIAL may appear instead. Change it for DELAY_BEFORE_SERIAL.

Set the references for code-sense

  • GCC_PREPROCESSOR_DEFINITIONS is the name of the micro-controller of the board, found in the boards.txt file.
GCC_PREPROCESSOR_DEFINITIONS = __AVR_ATmega328P__ ARDUINO
  • HEADER_SEARCH_PATHS needs to be updated with the reference of the IDE, with the full path in prefix and detailed folders ended with /** in suffix.

For example, for the Arduino Uno board, the correct reference is the following:

HEADER_SEARCH_PATHS = /Applications/Arduino.app/Contents/Java/hardware/arduino/avr/** $HOME/Library/Arduino15/packages/arduino/hardware/avr/**

For the Arduino Uno board, the reference is provided by two folders: one inside the Arduino application located at /Applications/Arduino.app, and another from the boards package located at $HOME/Library/Arduino15/packages.

The embedXcode+ edition allows to locate the Arduino IDE in another folder.

The embedXcode+ edition checks and updates the APPLICATIONS_PATH parameter automatically during the build process.

APPLICATIONS_PATH = /Applications
HEADER_SEARCH_PATHS = $HOME/Library/Arduino15/packages/arduino/hardware/avr/** $(APPLICATIONS_PATH)/Arduino.app/Contents/Java/hardware/arduino/avr/**

This parameter improves the selection of the headers for code-sense.

Set memory sizes

  • MAX_FLASH_SIZE gives the number of bytes of Flash. Read the specification sheet of the MCU to find the correct value.
MAX_FLASH_SIZE = 262144
  • MAX_RAM_SIZE gives the number of bytes of SRAM. Read the specification sheet of the MCU to find the correct value.
MAX_RAM_SIZE = 2048

Additional parameters for the programmer can be set according to the procedure Define a specific programmer for a new board .

Changes done to the board configuration file aren't updated automatically, because the parameters are loaded only once when the board configuration file is selected.

To take the new parameters into account,

  • Select another board.

  • Select again the board you are working on.

Define a specific programmer for a new board

Additionally, embedXcode+ offers options to use a different programmer on the same board configuration settings file.

This section applies to the boards supported by a Wiring / Arduino like IDE. The IDE includes the central file boards.txt contains all the parameters of the boards.

Set programmer options

Only specify the parameters when the values are different from the default ones.

  • AVRDUDE_SPECIAL states that a specific configuration is set for the programmer. Otherwise, comment the line.
AVRDUDE_SPECIAL = 1
  • AVRDUDE_PROGRAMMER provides the name of the specific programmer. Otherwise, the variable isn't required: just comment the line.
AVRDUDE_PROGRAMMER = usbtiny
  • AVRDUDE_BAUDRATE provides the speed for upload. If the speed differs from the default setting, specify it. Otherwise, the variable isn't required: just comment the line.
AVRDUDE_BAUDRATE = 9600
  • AVRDUDE_OTHER_OPTIONS provides a free variable, for example for selecting verbose output or erasing flash.
AVRDUDE_OTHER_OPTIONS = -v
  • If the programmer doesn't feature a serial port, set AVRDUDE_NO_SERIAL_PORT to 1.
AVRDUDE_NO_SERIAL_PORT = 1
  • Otherwise, set AVRDUDE_NO_SERIAL_PORT to O or comment the line. The port to be used is defined by BOARD_PORT.

Define boot-loader options

Only specify the parameters when the values are different from the default ones.

  • If the specific boot-loader is already supported like MiniCore for AVR MCUs, set BOOTLOADER to its name. 
BOOTLOADER = minicore
  • Otherwise, set the AVRDUDE_CONF variable to the specific avrdude.conf.
AVRDUDE_CONF = $(HOME)/Library/Arduino15/packages/MiniCore/hardware/avr/1.0.3/avrdude.conf

For more information on how to install the MiniCore boot-loader,

Define compatible MCU

Many ATmega MCUs are compatible and Arduino provides support to most of them. For example, the ATmega328 is compatible with the ATmega328P. However, Arduino doesn't support the ATmega328 but supports the ATmega328P.

  • If the speed is different, just define F_CPU, otherwise comment the line to use the default value provided by the IDE.
F_CPU = 20000000L

However, each MCU has a unique signature required by the programmer. For example, the signature of the ATmega328 is 0x1e 0x95 0x14 while the compatible ATmega328P has 0x1e 0x95 0x0f.

The programmer checks the signature of the MCU, so the exact reference of the MCU needs to be specified to AVRDUDE.

In that case,

  • Specify AVRDUDE_MCU as the MCU for the programmer only:
AVRDUDE_MCU = atmega328

Set fuses options

  • Optionally, fuses can be set, including ISP_LOCK_FUSE_PRE, ISP_LOCK_FUSE_POST, ISP_HIGH_FUSE, ISP_LOW_FUSE and ISP_EXT_FUSE.
ISP_LOCK_FUSE_PRE = 0x3f
ISP_LOCK_FUSE_POST = 0x0f
ISP_HIGH_FUSE = 0xde
ISP_LOW_FUSE = 0xff
ISP_EXT_FUSE = 0x05

If those variables aren't defined on the board configuration file, default values are provided by the IDE.

  • To by-pass the fuses, set AVR_IGNORE_FUSES to 1, otherwise set the value to 0 or comment the line.
AVR_IGNORE_FUSES = 1
  • Please refer to the documentation of the MCUs for the correct values. Incorrect values may damage the MCU.

Read warnings

You may also need to update the FTDI drivers to use a programmer.

Some options, as the values for the fuses, are critical and may freeze the MCU.

  • Please refer to the documentation provided by the manufacturers for the correct values, for example the Atmel website.

These options have been tested with the 5V FTDI basic programmer from Sparkfun, the USB tinyISP AVR programmer kit from Adafruit and the USB ASP programmer from Protostack.

Add a board to the templates

The Configurations group includes one board configuration called My board for the Wiring / Arduino framework or My Board (mbed) for the mbed framework. This specific board can be edited and included in the embedXcode+ template for later use in new projects.

  • To add a board to the templates,

  • Find and edit the board configuration My board under the Configurations group.

  • Open the Finder on the Documents folder and launch the Update My Board utility for the Wiring / Arduino framework.

  • Follow the instructions of the utility. Select the file My board.xcconfig or My Board and press Choose.

The utility copies the board configuration file into the embedXcode+ templates Example, Local Library and Sketch. Then it display a message.

  • Click OK to close the utility.

In case the selected file had an invalid extension, the utility stops and displays an error message.

  • Click OK to close the utility.

  • Create a new project.

The new My Board is now listed among the boards.