Handles generation and parsing of unique device identifiers for discovery and pairing.
More...
Handles generation and parsing of unique device identifiers for discovery and pairing.
This module enforces a strict naming convention for OpenThread devices to facilitate automatic discovery, logical grouping, and type identification. Naming Format: GroupName_DeviceType_EUI64 Example: kitchen_3_588c81fffe301ea4
- GroupName (kitchen): User-defined string used for grouping. Devices check this to decide if they should pair.
- DeviceType (3): Numeric identifier from otapp_deviceType_t (e.g., 3 = LIGHTING).
- EUI64 (588c...): Unique 64-bit hardware identifier ensuring name uniqueness on the network. This structure allows devices to filter traffic (e.g., "I am a Switch in group 'kitchen', I look for Lights in group 'kitchen'").
- Version
- 0.1
- Date
- 26-08-2025
- Author
- Jan Łukaszewicz (plhar.nosp@m.eo@g.nosp@m.mail..nosp@m.com)
- Copyright
- © 2025 MIT LICENCE
◆ OTAPP_DEVICENAME_BUFFER_TOO_SMALL
| #define OTAPP_DEVICENAME_BUFFER_TOO_SMALL (-5) |
Destination buffer insufficient.
◆ OTAPP_DEVICENAME_CALL_DEVICE_NAME_SET_FN
| #define OTAPP_DEVICENAME_CALL_DEVICE_NAME_SET_FN (-6) |
Name not initialized yet.
◆ OTAPP_DEVICENAME_ERROR
| #define OTAPP_DEVICENAME_ERROR (-2) |
Generic error (null ptr, invalid format).
◆ OTAPP_DEVICENAME_FULL_SIZE
Max size for full label (32 bytes).
◆ OTAPP_DEVICENAME_IS
| #define OTAPP_DEVICENAME_IS (1) |
◆ OTAPP_DEVICENAME_IS_NOT
| #define OTAPP_DEVICENAME_IS_NOT (2) |
Names/Groups do not match.
◆ OTAPP_DEVICENAME_MAX_DEVICE_TYPE
◆ OTAPP_DEVICENAME_MIN_ADD_DOMAIN_BUFFER_SIZE
Buffer safety margin for DNS domain.
◆ OTAPP_DEVICENAME_MIN_SIZE
Min required size for metadata.
◆ OTAPP_DEVICENAME_OK
| #define OTAPP_DEVICENAME_OK (-1) |
◆ OTAPP_DEVICENAME_SIZE
Max user GroupName length (~10 chars).
◆ OTAPP_DEVICENAME_TOO_LONG
| #define OTAPP_DEVICENAME_TOO_LONG (-3) |
String exceeds buffer limits.
◆ OTAPP_DEVICENAME_TOO_SHORT
| #define OTAPP_DEVICENAME_TOO_SHORT (-4) |
String is too short to be valid.
◆ otapp_deviceNameDelete()
| void otapp_deviceNameDelete |
( |
void | | ) |
|
Clears the internal device name buffer.
◆ otapp_deviceNameEuiIsSame()
| int8_t otapp_deviceNameEuiIsSame |
( |
const char * | deviceNameFull, |
|
|
const char * | eui ) |
Compares the EUI-64 in a name string with a raw EUI string.
- Parameters
-
| deviceNameFull | [in] Full device name string. |
| eui | [in] Hex string of the EUI to compare against. |
- Returns
- int8_t OTAPP_DEVICENAME_IS if match.
◆ otapp_deviceNameFullAddDomain()
| int8_t otapp_deviceNameFullAddDomain |
( |
char * | deviceFullName, |
|
|
uint16_t | bufLength ) |
Appends the OpenThread default service domain to a device name.
Transforms "device_name" into "device_name.default.service.arpa." for DNS-SD queries.
- Parameters
-
| [in,out] | deviceFullName | Buffer containing the name. Result is written back here. |
| [in] | bufLength | Size of the buffer (must be large enough). |
- Returns
- int8_t OTAPP_DEVICENAME_OK on success.
◆ otapp_deviceNameFullGet()
| const char * otapp_deviceNameFullGet |
( |
void | | ) |
|
Retrieves the current device's Full Name string.
- Returns
- const char* Pointer to the internal static buffer containing the name (e.g., "kitchen_3_588c81fffe301ea4").
◆ otapp_deviceNameFullIsSame()
| int8_t otapp_deviceNameFullIsSame |
( |
const char * | deviceNameFull | ) |
|
Checks if the provided full name string is identical to this device's name.
Used to prevent a device from pairing with itself during discovery.
- Parameters
-
| deviceNameFull | [in] String to compare. |
- Returns
- int8_t OTAPP_DEVICENAME_IS (match), OTAPP_DEVICENAME_IS_NOT (no match).
◆ otapp_deviceNameFullToEUI()
| int8_t otapp_deviceNameFullToEUI |
( |
const char * | deviceNameFull, |
|
|
uint8_t | stringLength, |
|
|
char ** | outEuiChrPtr ) |
Extracts the EUI-64 suffix from a Device Full Name.
Locates the last underscore and returns a pointer to the EUI hex string part.
- Parameters
-
| deviceNameFull | [in] Full name string. |
| stringLength | [in] Length of the string. |
| outEuiChrPtr | [out] Pointer to the start of the EUI string within the input buffer. |
- Returns
- int8_t OTAPP_DEVICENAME_OK or error.
◆ otapp_deviceNameGetDevId()
| int16_t otapp_deviceNameGetDevId |
( |
const char * | deviceNameFull, |
|
|
uint8_t | stringLength ) |
Extracts the Device Type ID from a Full Name string.
Parses the middle section of the name string (Name_TYPE_EUI).
- Parameters
-
| deviceNameFull | [in] Full name string. |
| stringLength | [in] Length of the string. |
- Returns
- int16_t Device Type ID (otapp_deviceType_t) or error code.
◆ otapp_deviceNameIsMatching()
| int8_t otapp_deviceNameIsMatching |
( |
const char * | deviceFullName | ) |
|
Determines if a discovered device is a valid candidate for pairing.
Checks two conditions:
- The device is NOT itself (otapp_deviceNameFullIsSame returns IS_NOT).
- The device belongs to the same Group (otapp_deviceNameIsSame returns IS).
- Parameters
-
| deviceFullName | Full name of the discovered device. |
- Returns
- int8_t OTAPP_DEVICENAME_IS if matching, otherwise IS_NOT or ERROR.
◆ otapp_deviceNameIsSame()
| int8_t otapp_deviceNameIsSame |
( |
const char * | deviceNameFull, |
|
|
uint8_t | stringLength ) |
Checks if the Group Name (prefix) matches this device's Group Name.
Parses the input string to extract the prefix (before the first '_') and compares it with the local device group. This determines if devices belong to the same logical group.
- Parameters
-
| deviceNameFull | [in] Full name string of the remote device. |
| stringLength | [in] Length of the string to check. |
- Returns
- int8_t OTAPP_DEVICENAME_IS (groups match), OTAPP_DEVICENAME_IS_NOT (different groups).
◆ otapp_deviceNameSet()
| int8_t otapp_deviceNameSet |
( |
const char * | deviceName, |
|
|
const otapp_deviceType_t | deviceType ) |
Sets the device Group Name and Type, generating the Full Name.
Constructs the full unique identifier string using the provided user name, device type, and the hardware EUI64 address obtained from the OpenThread stack.
- Parameters
-
| deviceName | [in] User-defined group name (e.g., "kitchen"). Max ~10 chars. |
| deviceType | [in] Device functional type (otapp_deviceType_t). |
- Returns
- int8_t OTAPP_DEVICENAME_OK on success, or error code.
◆ otapp_hostNameToDeviceNameFull()
| int8_t otapp_hostNameToDeviceNameFull |
( |
char * | hostName | ) |
|
Strips the domain suffix to extract the pure Device Full Name.
Transforms "device_name.default.service.arpa." back into "device_name". Modifies the input buffer by inserting a null terminator.
- Parameters
-
| [in,out] | hostName | Buffer containing the full DNS hostname. |
- Returns
- int8_t OTAPP_DEVICENAME_OK on success.
1.15.0