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": "0.0.0.0", "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 fall back 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 fall back to the environment named "default". If no such environment is defined in the project configuration file, Bloom will fail to startup.

Debug session configuration

shutdownPostDebugSession

The shutdownPostDebugSession boolean parameter determines whether Bloom will shutdown at the end of a debug session.

"environments": { "someEnvironmentName": { "shutdownPostDebugSession": true, "debugTool": { ... }, "target": { ... } } }

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 the following 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 (EDBG) "xplained-pro"
Xplained Mini Evaluation Board (mEDBG) "xplained-mini"
Xplained Nano Evaluation Board (mEDBG) "xplained-nano"
Curiosity Nano Evaluation Board (nEDBG) "curiosity-nano"
MPLAB PICkit 4 (in AVR mode) "pickit-4"
JTAGICE3 (firmware version 3.x+) "jtagice3"

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.

When using the JTAG physical interface, the target's JTAGEN and OCDEN fuse bits must be programmed. The OCDEN fuse bit is not programmed by default. Bloom will fail to operate correctly if the JTAGEN or OCDEN fuse bits are not programmed.

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

This parameter was introduced in version 0.5.0.

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.

updateDwenFuseBit

This parameter was introduced in version 0.7.0.

Bloom can automatically update the "debugWire enable" (DWEN) fuse bit on debugWire targets, upon a connection failure when attempting to connect via the debugWire physical interface. The updateDwenFuseBit boolean parameter is used to control this function.

CAUTION: Updating target fuses is a potentially dangerous operation. If done incorrectly, the target may become inaccessible for programming and may require high-voltage programming to recover. Whilst Bloom can update the DWEN fuse automatically, there is no guarantee that such an operation will be successful and not result in any damage to the target. Bloom is provided "AS IS", without warranty of any kind. You are using Bloom at your own risk. In no event shall Bloom's copyright owner or contributors be liable for any damage caused as a result of using Bloom. For more details, see the Bloom license.


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

If the updateDwenFuseBit parameter is set to true, upon initial failure to connect to the target via the debugWire physical interface, Bloom will make an attempt to connect to the target via its ISP interface. If successful, it will inspect the target's DWEN fuse bit and update it, if need be. Upon updating the fuse bit, Bloom will make a final attempt to connect to the target via the debugWire physical interface.

The updateDwenFuseBit parameter is optional. Its default value is false.

See debugging AVR microcontrollers via debugWire for more information.

The updateDwenFuseBit function cannot be used in conjunction with the generic "avr8" target name. The specific target name must be specified in the target configuration, in order for Bloom to manage the DWEN fuse bit.

This parameter has no effect in non-debugWire sessions.

cycleTargetPowerPostDwenUpdate

This parameter was introduced in version 0.8.0.

For debugWire targets, users may be required to cycle the target power after updating the DWEN fuse bit. Some debug tools provide functions to control the connected target's power input without any action being required by the user. Bloom utilises these functions to cycle target power after updating the target's DWEN fuse bit.

If the cycleTargetPowerPostDwenUpdate parameter is set to true, Bloom will cycle the target power after updating the target's DWEN fuse bit and before making a final connection attempt via debugWire.

The cycleTargetPowerPostDwenUpdate parameter is optional. Its default value is true.

This parameter has no effect in non-debugWire sessions, sessions where the selected debug tool does not provide target power management functions, or sessions where the updateDwenFuseBit parameter is set to false.

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 fall back 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.

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.

Other configuration

debugLoggingEnabled

Boolean parameter to enable the debug log output. This parameter should reside in the root object of bloom.json:

{ "debugLoggingEnabled": true, "environments": { ... }, ... }