Home Getting Started Download Discussions 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 eight debug tools:

Debug tool name Configuration value
Atmel-ICE "atmel-ice"
Power Debugger "power-debugger"
MPLAB Snap (in AVR mode) "snap"
Xplained Pro Evaluation Board "xplained-pro"
Xplained Mini Evaluation Board "xplained-mini"
Xplained Nano Evaluation Board "xplained-nano"
Curiosity Nano Evaluation Board "curiosity-nano"
MPLAB PICkit 4 (in AVR mode) "pickit-4"

To use the MPLAB Snap or PICkit 4 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 & PICkit 4


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 boolean parameter 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.

disableDebugWirePreDisconnect

For AVR8 targets with the debugWire physical interface, control of the reset pin is lost once the debugWire module has been enabled (via the DWEN fuse). This means that, until the debugWire module has been disabled, other interfaces which utilise the reset pin (such as SPI) will be unavailable.

Bloom possesses the ability to temporarily disable the debugWire module (without resetting the DWEN fuse). Once the debugWire module has been temporarily disabled, other interfaces such as SPI will become available. The debugWire module will remain disabled until power to the target is cycled. The disableDebugWirePreDisconnect boolean parameter can be used to enable this function.

"target": { "name": "atmega328p", "physicalInterface": "debug-wire", "disableDebugWirePreDisconnect": true }

If the disableDebugWirePreDisconnect parameter is set to true, Bloom will automatically disable the debugWire module, in a temporary fashion, before disconnecting from the target. Users can then proceed to use other interfaces that require control of the reset pin, up until power to the target has been cycled.

The disableDebugWirePreDisconnect parameter is optional. The default value is false.

With the disableDebugWirePreDisconnect function enabled, the power to the target must be cycled before attempting to reconnect to the target via Bloom.

It is not recommended to enable the disableDebugWirePreDisconnect option, along with the releasePostDebugSession option. With both options enabled, Bloom will effectively disable the debugWire module at the end of each debug session. This will result in the user being required to cycle the target power before almost every debug session.

The disableDebugWirePreDisconnect parameter was introduced in version 0.5.0.

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? Default value Description
ipAddress String No 127.0.0.1 The IP address on which the server will listen, for GDB RSP client connections.
port Integer No 1442 The port on which the server will listen, for GDB RSP client connections.

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.