Configuration

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.

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 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

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:
  # 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

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 YAML mapping, describing the selected debug tool. At the very least, this mapping should consist of the debug tool name.

name

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

debugTool:
  name: "atmel-ice"

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 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

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

debugTool:
  name: "atmel-ice"
  releasePostDebugSession: true

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 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 target.

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

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.

target

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

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

target:
  name: "atxmega16c4"

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"

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. Use the manageOcdenFuseBit target parameter to have Bloom automatically manage the OCDEN fuse bit.

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.

manageDwenFuseBit

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 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"
  manageDwenFuseBit: true

If the 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.

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

See debugging AVR microcontrollers via debugWire for more information.

The 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.

cycleTargetPowerPostDwenUpdate

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 manageDwenFuseBit parameter is set to false.

manageOcdenFuseBit

This parameter was introduced in version 0.12.0.

Bloom can automatically update the "OCD enable" (OCDEN) fuse bit on JTAG-enabled targets (excluding XMEGA). The manageOcdenFuseBit boolean parameter is used to control this function.

target:
  name: "atmega32a"
  physicalInterface: "jtag"
  manageOcdenFuseBit: true

If the manageOcdenFuseBit parameter is set to true, Bloom will inspect the OCDEN fuse bit upon target activation, and ensure that it's set to the appropriate value during the debug session. At the end of a debug session, Bloom will update the OCDEN fuse bit to disable the OCD, before disconnecting from the target.

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

preserveEeprom

This parameter was introduced in version 0.12.0.

When programming JTAG and UPDI targets, Bloom must perform a chip-erase on the target. As a result, EEPROM data will be erased. When the preserveEeprom parameter is set to true, Bloom will back up the EEPROM before triggering the chip-erase. Upon completion of the chip-erase, the backup will be restored.

target:
  name: "atmega32a"
  physicalInterface: "jtag"
  preserveEeprom: false

The backup-erase-restore process can take some time to complete. Setting the preserveEeprom parameter to false will reduce the time needed to program the AVR target.

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

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 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 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 or String	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 YAML mapping. Like the debugServer parameter, insight can be specified at the environment level or the project level.

Currently, the enabled boolean parameter is the only parameter available within the Insight configuration mapping:

insight:
  enabled: false

When enabled is set to false, the Insight component will be disabled - Bloom will run in a headless fashion.

Other configuration

debugLoggingEnabled

Boolean parameter to enable the debug log output.

debugLoggingEnabled: true

environments:
  someEnvironmentName:
    ...
  someOtherEnvironmentName:
    ...