Configuring HappyBrackets

#Configuring HappyBrackets#

HappyBrackets does it's best to have sensible defaults for much of it's configuration. Some days these defaults may not be quite right. Fear not for you can change them with configuration files :)

There are two configuration files:

• device_config.json contains settings that are used by the device. It lives on the device in ~/HappyBrackets/config.

• controller_config.json contains settings that are used by the HappyBrackets plugin. It lives in a specific plugin location and can be edited from within the plugin.

Editing your configuration files

As you may have guessed from the file extension HappyBrackets employs the common JSON format for it's configuration files. HappyBrackets may have trouble starting if there are syntax errors in your JSON. You can use a JSON editing plugin in your IDE to edit these (Intellij should prompt you to install this the first time you open a .json file). If you are doing this outside of an IDE you can copy and paste the JSON into an online JSON linting tool to make sure there aren't any errors.

A note on syntax

In the examples below you may notice that some values are quoted and some are not. JSON infers the types of parameters by their formatting so how you write it is important!

If the parameter is quoted this means it is a string like so:

{
  "compositionsPath": "compositions"
}

If the parameter is a boolean type it must be either true or false:

{
  "useHostname":      true
}

If the parameter is of a numeric type, such as an integer or a rational value it should be a number and without quotes:

{
  "polyLimit":   4,
  "pi":          3.14159265359
}

In the examples below the types used in the JSON are the types which HappyBrackets will accept. If you imply the wrong type in your config file you may prevent HappyBrackets from accepting the configuration file and subsequently prevent the application from starting. If you would like more information on the JSON format there exists a wealth o tutorials and other references, to begin with you might try: [W3C JSON tutorial] (http://www.w3schools.com/json/)

Common parameters

In Happybrackets there are a number of properties which are shared in both devices and the controller. These parameters are often not stated in config files because they all default back to net.happybrackets.config.EnvironmentConfig.java. The common parameters and their defaults are:

{
  "multicastAddr":            "225.2.2.5",
  "broadcastPort":            2222,
  "statusFromDevicePort":     2223,
  "clockSynchPort":           2224,
  "codeToDevicePort":         2225,
  "controlToDevicePort":      2226,
  "controllerDiscoveryPort":  2227,
  "controllerHTTPPort":       2228,
  "aliveInterval":            1000,
  "useHostname":              true,
  "encryptionKey":            "abc123"
}

These common parameters are configurable but they must be matching in both your device and controller configuration files.

• multicastAddr: address on which multicast/broadcast messages are sent.
• broadcastPort: port on which multicast/broadcast messages are sent.
• statusFromDevicePort: port on which device status messages are sent.
• clockSynchPort: port on which synchronisation messages are sent.
• codeToDevicePort: port on which code is sent to device.
• controlToDevicePort: port on which control messages are sent to device.
• controllerDiscoveryPort: port on which controller advertises its presence.
• controllerHTTPPort: port on which HTTP operates.
• aliveInterval: interval between heartbeat messages from device.
• useHostname: attempt to resolve hostnames rather than use IP addresses (better on Mac/Linux, worse on Windows).
• encryptionKey: the key (password) used to encrypt class files sent from the controller to the device(s).

Note on useHostname: if true the device will broadcast a nice name to the controller. For compatibility with non-zeroconf enabled systems (This is a common issue if you are running Windows) you can disable this option by setting it to false. If it is false the device will identify itself with an IPv4 address to the controller.

Device Configuration

The following are specific to devices only:

{
    "polyLimit":   4
}

• polyLimit controls the maximum number of sounds which may be generated at any given time. This option provides a mechanism for controlling the the performance impact of a composition, ensuring a glitch free playback.

Controller Configuration

The following are specific to the controller only:

{
  "compositionsPath": "compositions",
  "knowDevicesFile": "known_devices",
  "workingDir":       "."
}

• compositionsPath The path to your compositions directory
• knowDevicesFile The path to you known_devices file
• workingDir The path to your HappyBrackets project directory