Bluetooth: ISO: Document usage of broadcast code

Add a short example of how the broadcast code for BIGs shall
be used.

The spec states:
"On all levels other than UI, the Broadcast Code parameter shall be
 represented as a 128-bit value. The transformation from string to
 number shall be by representing the string in UTF-8, placing the
 resulting bytes in 8-bit fields of the value starting at the least
 significant bit, and then padding with zeros in the most
 significant bits if necessary. For example, the string “Børne
 House” is represented as the value
 0x00000000_6573756F_4820656E_72B8C342.
"

So "Børne House" becomes
[42, C3, B8, 72, 63, 65, 20, 48, 6F, 75, 73, 65, 00, 00, 00, 00]
when sending over HCI.

Signed-off-by: Emil Gydesen <[email protected]>

Author: Thalley

include/zephyr/bluetooth/audio/audio.h

@@ -2091,7 +2091,16 @@ struct bt_audio_broadcast_source_create_param {
 	/** Whether or not to encrypt the streams. */
 	bool encryption;
 
-	/** @brief Broadcast code */
+	/**
+	 * @brief Broadcast code
+	 *
+	 * If the value is a string or a the value is less than 16 octets,
+	 * the remaining octets shall be 0.
+	 *
+	 * Example:
+	 *   The string "Broadcast Code" shall be
+	 *   [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
+	 */
 	uint8_t broadcast_code[BT_BAP_BROADCAST_CODE_SIZE];
 };
 
@@ -2262,6 +2271,12 @@ int bt_audio_broadcast_sink_scan_stop(void);
  *  @param broadcast_code     The 16-octet broadcast code. Shall be supplied if
  *                            the broadcast is encrypted (see the syncable
  *                            callback).
+ *                            If the value is a string or a the value is less
+ *                            than 16 octets, the remaining octets shall be 0.
+ *
+ *                            Example:
+ *                            The string "Broadcast Code" shall be
+ *                            [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
  *
  *  @return 0 in case of success or negative value in case of error.
  */

include/zephyr/bluetooth/audio/cap.h

@@ -271,9 +271,17 @@ struct bt_cap_broadcast_audio_start_param {
 	 */
 	bool encrypt;
 
-	/** 16-octet broadcast code.
+	/**
+	 * @brief 16-octet broadcast code.
 	 *
 	 * Only valid if @p encrypt is true.
+	 *
+	 * If the value is a string or a the value is less than 16 octets,
+	 * the remaining octets shall be 0.
+	 *
+	 * Example:
+	 *   The string "Broadcast Code" shall be
+	 *   [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
 	 */
 	uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
 };
@@ -344,9 +352,17 @@ struct bt_cap_unicast_to_broadcast_param {
 	 */
 	bool encrypt;
 
-	/** 16-octet broadcast code.
+	/**
+	 * @brief 16-octet broadcast code.
 	 *
 	 * Only valid if @p encrypt is true.
+	 *
+	 * If the value is a string or a the value is less than 16 octets,
+	 * the remaining octets shall be 0.
+	 *
+	 * Example:
+	 *   The string "Broadcast Code" shall be
+	 *   [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
 	 */
 	uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
 };

include/zephyr/bluetooth/iso.h

@@ -349,6 +349,13 @@ struct bt_iso_big_create_param {
 	 *
 	 *  The code used to derive the session key that is used to encrypt and
 	 *  decrypt BIS payloads.
+	 *
+	 *  If the value is a string or a the value is less than 16 octets,
+	 *  the remaining octets shall be 0.
+	 *
+	 *  Example:
+	 *    The string "Broadcast Code" shall be
+	 *    [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
 	 */
 	uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE];
 };
@@ -396,6 +403,13 @@ struct bt_iso_big_sync_param {
 	 *
 	 *  The code used to derive the session key that is used to encrypt and
 	 *  decrypt BIS payloads.
+	 *
+	 *  If the value is a string or a the value is less than 16 octets,
+	 *  the remaining octets shall be 0.
+	 *
+	 *  Example:
+	 *    The string "Broadcast Code" shall be
+	 *    [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
 	 */
 	uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE];
 };