All Bloom enabled projects must contain a single project configuration file (bloom.yaml) in the directory from which Bloom is expected to be run (typically the project root directory).
The YAML configuration file describes the environment(s) in which debugging will be performed. This includes debug tool, target and debug server configuration.
Prior to version 0.11.0, project configuration files were required to be in JSON format. The recommended format was changed to YAML in version 0.11.0.
To minimise disruption for current users, Bloom still supports JSON configuration files and will fall back to bloom.json in the absence of bloom.yaml.
Creating a project configuration file
init command will create a project configuration file in the working
$ cd /path/to/project; $ bloom init;
The contents of the newly created bloom.yaml file should closely resemble the following:
environments: default: debugTool: name: "atmel-ice" target: name: "avr8" physicalInterface: "debug-wire" debugServer: name: "avr-gdb-rsp" ipAddress: "127.0.0.1" port: 1442 insight: enabled: true
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: # Configuration for the "default" environment. # Bloom will fall back to the "default" environment when no environment name # has been passed as an argument. default: debugTool: name: "atmel-ice" target: name: "avr8" physicalInterface: "debug-wire" # Configuration for the "lab-remote" environment. In this environment, we use a # different debug tool, disable the Insight GUI and have the GDB server listen # on a different port. lab-remote: debugTool: name: "power-debugger" target: name: "avr8" physicalInterface: "debug-wire" debugServer: name: "avr-gdb-rsp" ipAddress: "0.0.0.0" port: 1655 insight: enabled: false # Debug server and Insight configuration can be provided at the project # level, as well as the environment level. If an environment doesn't # include debug server or Insight configuration, Bloom will fall back to # project level configuration. # # In this example, the "default" environment does not define any debug server # or Insight configuration, so the project level configuration, defined below, # will be used. However, the "lab-remote" environment *does* include debug # server and Insight configuration, so that (environment level) configuration # will take precedence over the configuration below. 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" mapping).
To select an environment, simply include the environment name as an argument when running Bloom:
$ bloom lab-remote
Environment names must only consist of ASCII characters and 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 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
This should take the form of a YAML mapping, describing the selected debug tool. At the very least, this mapping should consist of the debug tool name.
The debug tool name can be specified via the
debugTool: name: "atmel-ice"
Bloom supports the following debug tools:
|Debug tool name||Configuration value|
|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 configured to run in 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 boolean parameter determines whether Bloom will
release the debug tool at the end of a debug session.
debugTool: name: "atmel-ice" releasePostDebugSession: true
releasePostDebugSession is set to
Bloom will enter a suspended state once the current debug session has ended. Bloom's control of the
debug tool and target will cease, allowing other applications to gain access to the hardware. If set
false, Bloom will remain in an active state post debug session,
preventing other applications from accessing the debug tool and target.
releasePostDebugSession parameter is optional. The default value is
When running Bloom under certain CLion debug configurations, CLion expects Bloom to shutdown once the debug session has ended.
Since version 0.11.0, Bloom will shutdown automatically if its process is being managed by CLion.
This should take the form of a YAML mapping, describing the connected target. At the very least, this mapping should consist of the target name, but targets typically require additional configuration, depending on 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
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.
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|
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.
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.
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.
disableDebugWirePreDisconnect boolean parameter can be used to enable
target: name: "atmega328p" physicalInterface: "debug-wire" disableDebugWirePreDisconnect: true
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.
disableDebugWirePreDisconnect parameter is optional. The default
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.
disableDebugWirePreDisconnect parameter was introduced in version
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
manageDwenFuseBit boolean parameter is used to control
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" manageDwenFuseBit: true
manageDwenFuseBit 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.
manageDwenFuseBit parameter is optional. Its default value is
See debugging AVR microcontrollers via debugWire for more information.
manageDwenFuseBit 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.
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.
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.
cycleTargetPowerPostDwenUpdate parameter is optional. Its default value
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
manageDwenFuseBit parameter is set to
The specific target package variant can be specified via the
target: name: "atmega328p" physicalInterface: "debug-wire" variantName: "atmega328p-pu"
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
parameter. This takes the form of a YAML mapping. 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
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 or String||No||1442||The port on which the server will listen, for GDB RSP client connections.|
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 YAML mapping. Like the
insight can be specified at the environment level or the project level.
enabled boolean parameter is the only parameter available
within the Insight configuration mapping:
insight: enabled: false
enabled is set to
false, the Insight
component will be disabled - Bloom will run in a headless fashion.
Boolean parameter to enable the debug log output.
debugLoggingEnabled: true environments: someEnvironmentName: ... someOtherEnvironmentName: ...