Home Getting Started About Download Source Report An Issue

Configuration

All Bloom enabled projects must contain a single project configuration file (bloom.json) in the directory from which Bloom is expected to be run (typically the project root directory).

The configuration file is a JSON file that describes the environment(s) in which debugging will be performed.

Creating a project configuration file

The init command will create a project configuration file in the working directory:

$ cd /path/to/project; $ bloom init;

The contents of the newly created configuration file should closely resemble the following:

{ "environments": { "default": { "debugTool": { "name": "atmel-ice", "releasePostDebugSession": true }, "target": { "name": "avr8", "physicalInterface": "debug-wire" } } }, "debugServer": { "name": "avr-gdb-rsp", "ipAddress": "127.0.0.1", "port": "1442" }, "insight": { "enabled": true } }

Project environments

For projects where debugging can take place in numerous environments, Bloom provides the ability to describe each environment in the project configuration file. An environment can then be selected by name, via an argument passed to Bloom.

In the example below, we define two environments; one named "default" and the other "lab-remote". The "lab-remote" environment selects a different debug tool and debug server port, as well as disabling Insight.

{ "environments": { "default": { "debugTool": { "name": "atmel-ice", "releasePostDebugSession": true }, "target": { "name": "avr8", "physicalInterface": "debug-wire" } }, "lab-remote": { "debugTool": { "name": "power-debugger", "releasePostDebugSession": true }, "target": { "name": "avr8", "physicalInterface": "debug-wire" }, "debugServer": { "name": "avr-gdb-rsp", "ipAddress": "127.0.0.1", "port": "1655" }, "insight": { "enabled": false } } }, "debugServer": { "name": "avr-gdb-rsp", "ipAddress": "127.0.0.1", "port": "1442" }, "insight": { "enabled": true } }

Debug server and Insight configuration can be defined at a project or environment level. If an environment doesn't include debug server or Insight configuration, Bloom will fallback to project level configuration. In the example above, the "default" environment does not include any debug server or Insight configuration, but this is included at the project level (proceeding the "environments" object).

To select an environment, simply include the environment name as an argument when running Bloom:

$ bloom lab-remote

Environment names must not conflict with command names ("init", "--help", "--version", etc).

If an environment name is not provided, Bloom will fallback to the environment named "default". If no such environment is defined in the project configuration file, Bloom will fail to startup.

Debug tool and target configuration

As a bare minimum, each environment should define a debugTool and target.

debugTool

This should take the form of a JSON object, describing the selected debug tool. At the very least, this object should consist of the debug tool name.

name

The debug tool name can be specified via the name parameter:

"debugTool": { "name": "atmel-ice" }

Currently, Bloom supports three debug tools:

Debug tool name Configuration value
Atmel-ICE "atmel-ice"
Power Debugger "power-debugger"
MPLAB Snap (in AVR mode) "snap"

To use the MPLAB Snap debug tool, you must first ensure that it has been flashed into AVR mode. If it is not in AVR mode, Bloom will fail to recognise it. This can be done via Microchip's MPLAB IPE software. See Enabling "AVR mode" on the MPLAB Snap


Furthermore, to use the MPLAB Snap in conjunction with the PDI or UPDI physical interfaces, the following interfacing issue may need to be taken into consideration: MPLAB Snap AVR UPDI/PDI/TPI Interface Modification. A temporary solution would be to use an external 1-10K pull-up resistor on the PDI/UPDI line (pin 4 on the J4 connector). See the linked document for more information.

releasePostDebugSession

The releasePostDebugSession parameter is a boolean flag that determines whether Bloom will release the debug tool at the end of a debug session.

If releasePostDebugSession is set to true, Bloom will enter a suspended state once the current debug session has ended. Bloom's control of the debug tool and thus the connected target will cease, allowing other applications to gain access to the hardware. If set to false, Bloom will remain in an active state post debug session, preventing other applications from accessing the debug tool and thus the connected target.

It is recommended that releasePostDebugSession is enabled, as it will allow users to run other applications which require access to the debug tool, between debug sessions. Consider, for example, the need to program the target in between debug sessions.

The releasePostDebugSession parameter is optional. The default value is true.

target

This should take the form of a JSON object, describing the connected target. At the very least, this object should consist of the target name, but targets typically require additional configuration, depending on the target.

Currently, Bloom only supports targets from the AVR 8-bit family.

name

The target name should be the marketing name of the target:

"target": { "name": "atxmega16c4" }

Alternatively, for AVR8 targets, providing the generic "avr8" value in the target name will allow Bloom to automatically identify the target. However, this may not work in some cases; Bloom uses the AVR target signature to identify the target, but some AVR8 targets share the same signature. In these cases, using the generic "avr8" value will result in an "ambiguous signature" error during startup. The error message will include a list of the matching target names, from which the correct name must be selected.

The generic "avr8" target configuration cannot be used in conjunction with the JTAG or UPDI physical interfaces.

For a complete list of supported targets, along with their associated configuration values, see Supported Targets.

The value for name is case-insensitive.

physicalInterface

AVR8 targets require one additional configuration value: the physicalInterface. This parameter specifies the interface between the debug tool and the target.

"target": { "name": "atmega328p", "physicalInterface": "debug-wire" }
Physical interface name Configuration value
debugWire "debug-wire"
PDI "pdi"
JTAG "jtag"
UPDI "updi"

The value for physicalInterface is case-insensitive.

NOTE: When using the MPLAB Snap in conjunction with the PDI or UPDI physical interfaces, the following interfacing issue may need to be taken into consideration: MPLAB Snap AVR UPDI/PDI/TPI Interface Modification


A temporary solution would be to use an external 1-10K pull-up resistor on the PDI/UPDI line (pin 4 on the J4 connector). See the linked document for more information.

variantName

The specific target package variant can be specified via the variantName parameter:

"target": { "name": "atmega328p", "physicalInterface": "debug-wire", "variantName": "atmega328p-pu" }

If variantName is set, the Insight window will select the specified variant at startup. If Insight is disabled, this parameter will have no effect.

Debug server configuration

Configuration for the debug server must be specified via the debugServer parameter. This takes the form of a JSON object. The debugServer can be specified at the environment level or the project level. If the selected environment defines debugServer, the project level definition will be ignored. Otherwise, Bloom will fallback to the project level definition. If debugServer is not defined for the selected environment and no project level definition exists, Bloom will fail to startup.

Currently, Bloom only supports one debug server: The AVR GDB RSP Debug Server. To use this server, the name "avr-gdb-rsp" must be specified in the name parameter:

"debugServer": { "name": "avr-gdb-rsp" }

The AVR GDB RSP server allows for some additional parameters to be specified:

Parameter Value type Required? Description
ipAddress String No The IP address the server will listen on, for GDB RSP client connections. If this is not specified, the default value of 127.0.0.1 will be used.
port Integer No The port the server will listen on, for GDB RSP client connections. If this is not specified, the default value of 1442 will be used.

Insight configuration

Bloom Insight provides insight into the connected target via a GUI. See Using Bloom Insight for more.

Configuration for Insight can be specified via the insight parameter. This takes the form of a JSON object. Like the debugServer parameter, insight can be specified at the environment level or the project level.

insight configuration is not required.

Currently, the enabled parameter is the only parameter available within the Insight configuration object. It should take the form of a boolean (not a string - do not wrap the value in quotes):

"insight": { "enabled": false }

When enabled is set to false, the Insight component will be disabled - it will cease to load on startup.