nl::PairingCode

Summary

Enumerations
`@353`	enum
`@354`	enum
`@355`	enum
`@356{ kStandardPairingCodeLength = 6, kKryptonitePairingCodeLength = 9, kPairingCodeLenMin = 2, kBitsPerCharacter = 5 }`	enum

Functions
`GeneratePairingCode(uint8_t pairingCodeLen, char *outBuf)`	`WEAVE_ERROR` Generate a random pairing code.
`IntToPairingCode(uint64_t val, uint8_t pairingCodeLen, char *outBuf)`	`WEAVE_ERROR` Encode an integer value as a Weave pairing code.
`IntToPairingCodeChar(int val)`	`char` Convert an integer value in the range 0..31 to its corresponding Weave pairing code character.
`IsValidPairingCodeChar(char ch)`	`bool` Returns true if a supplied character is a valid Weave pairing code character.
`KryptoniteDeviceIdToPairingCode(uint64_t deviceId, char *pairingCodeBuf, size_t pairingCodeBufSize)`	`WEAVE_ERROR` Generates a Kryptonite pairing code string given a Kryptonite device id.
`KryptonitePairingCodeToDeviceId(const char *pairingCode, uint64_t & deviceId)`	`WEAVE_ERROR` Returns the device ID encoded in Kryptonite pairing code.
`NevisDeviceIdToPairingCode(uint64_t deviceId, char *pairingCodeBuf, size_t pairingCodeBufSize)`	`WEAVE_ERROR` Generates a Nevis pairing code string given a Nevis device id.
`NevisPairingCodeToDeviceId(const char *pairingCode, uint64_t & deviceId)`	`WEAVE_ERROR` Returns the device ID encoded in Nevis pairing code.
`NormalizePairingCode(char *pairingCode, size_t & pairingCodeLen)`	`void` Normalize the characters in a pairing code string.
`PairingCodeCharToInt(char ch)`	`int` Convert a Weave pairing code character to an integer value in the range 0..31.
`PairingCodeToInt(const char *pairingCode, size_t pairingCodeLen, uint64_t & val)`	`WEAVE_ERROR` Decode a Weave pairing code as an integer value.
`VerifyPairingCode(const char *pairingCode, size_t pairingCodeLen)`	`WEAVE_ERROR` Verify a Weave pairing code against its check character.

Enumerations

@353

 @353

@354

 @354

@355

 @355

@356

 @356

Properties
`kBitsPerCharacter`	Number of bits encoded in a single pairing code character.
`kKryptonitePairingCodeLength`	Pairing code length for Kryptonite.
`kPairingCodeLenMin`	Minimum length of a pairing code.
`kStandardPairingCodeLength`	Pairing code length for most Nest products.

Functions

GeneratePairingCode

WEAVE_ERROR GeneratePairingCode(
  uint8_t pairingCodeLen,
  char *outBuf
)

Generate a random pairing code.

The function generates a random Weave pairing code string with a specified length. value, encoded as a big-endian, base-32 numeral, plus a trailing Verhoeff check character. The generated string has a fixed length specified by the pairingCodeLen parameter. The string is padded on the left with zeros as necessary to meet this length.

Details

Parameters

`[in] pairingCodeLen`	The desired length of the pairing code string, including the trailing check character. Must be >= 2.
`[out] outBuf`	A pointer to a character buffer that will receive the encoded pairing code, plus a null terminator character. The supplied buffer should be at least as big as pairingCodeLen + 1.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If pairingCodeLen is < 2 or the supplied integer value cannot be encoded in the number of characters specified by pairingCodeLen, minus 1 for the check character.

IntToPairingCode

WEAVE_ERROR IntToPairingCode(
  uint64_t val,
  uint8_t pairingCodeLen,
  char *outBuf
)

Encode an integer value as a Weave pairing code.

The function generates a Weave pairing code string consisting of a supplied unsigned integer value, encoded as a big-endian, base-32 numeral, plus a trailing Verhoeff check character. The generated string has a fixed length specified by the pairingCodeLen parameter. The string is padded on the left with zeros as necessary to meet this length.

Details

Parameters

`[in] val`	The value to be encoded.
`[in] pairingCodeLen`	The desired length of the encoded pairing code string, including the trailing check character. Must be >= 2.
`[out] outBuf`	A pointer to a character buffer that will receive the encoded pairing code, plus a null terminator character. The supplied buffer should be at least as big as pairingCodeLen + 1.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If pairingCodeLen is < 2 or the supplied integer value cannot be encoded in the number of characters specified by pairingCodeLen, minus 1 for the check character.

IntToPairingCodeChar

char IntToPairingCodeChar(
  int val
)

Convert an integer value in the range 0..31 to its corresponding Weave pairing code character.

Note that this function always produces upper-case characters.

Details

Parameters

[in] val

The integer value to be converted.

Returns

The pairing code character that corresponds to the specified integer value, or 0 if the integer value is out of range.

IsValidPairingCodeChar

bool IsValidPairingCodeChar(
  char ch
)

Returns true if a supplied character is a valid Weave pairing code character.

Note that this function is case-insensitive.

Details

Parameters

[in] ch

The character to be tested.

Returns

True if a supplied character is a valid Weave pairing code character.

KryptoniteDeviceIdToPairingCode

WEAVE_ERROR KryptoniteDeviceIdToPairingCode(
  uint64_t deviceId,
  char *pairingCodeBuf,
  size_t pairingCodeBufSize
)

Generates a Kryptonite pairing code string given a Kryptonite device id.

Details

Parameters

`[in] deviceId`	A Kryptonite device id.
`[out] pairingCodeBuf`	A pointer to a buffer that will receive the Kryptonite pairing code, a NULL termination character. The supplied buffer should be 7 characters or more in size.
`[in] pairingCodeBufSize`	The size of the buffer pointed at by pairingCodeBuf.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the supplied device id is out of range, or if the supplied buffer is too small.

KryptonitePairingCodeToDeviceId

WEAVE_ERROR KryptonitePairingCodeToDeviceId(
  const char *pairingCode,
  uint64_t & deviceId
)

Returns the device ID encoded in Kryptonite pairing code.

Details

Parameters

`[in] pairingCode`	A NULL-terminated string containing a Kryptonite pairing code.
`[out] deviceId`	A reference to an integer that receives the decoded Kryptonite device id.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the length of the supplied pairing code is incorrect, or if the pairing code contains invalid characters, or if the initial characters of the pairing code are not consistent with the check character.

NevisDeviceIdToPairingCode

WEAVE_ERROR NevisDeviceIdToPairingCode(
  uint64_t deviceId,
  char *pairingCodeBuf,
  size_t pairingCodeBufSize
)

Generates a Nevis pairing code string given a Nevis device id.

Details

Parameters

`[in] deviceId`	A Nevis device id.
`[out] pairingCodeBuf`	A pointer to a buffer that will receive the Nevis pairing code, a NULL termination character. The supplied buffer should be 7 characters or more in size.
`[in] pairingCodeBufSize`	The size of the buffer pointed at by pairingCodeBuf.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the supplied device id is out of range, or if the supplied buffer is too small.

NevisPairingCodeToDeviceId

WEAVE_ERROR NevisPairingCodeToDeviceId(
  const char *pairingCode,
  uint64_t & deviceId
)

Returns the device ID encoded in Nevis pairing code.

Details

Parameters

`[in] pairingCode`	A NULL-terminated string containing a Nevis pairing code.
`[out] deviceId`	A reference to an integer that receives the decoded Nevis device id.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If the length of the supplied pairing code is incorrect, or if the pairing code contains invalid characters, or if the initial characters of the pairing code are not consistent with the check character.

NormalizePairingCode

void NormalizePairingCode(
  char *pairingCode,
  size_t & pairingCodeLen
)

Normalize the characters in a pairing code string.

This function converts all alphabetic characters to upper-case, maps the illegal characters 'I', 'O', 'Q' and 'Z' to '1', '0', '0' and '2', respectively, and removes all other non-pairing code characters from the given string.

The input string is not required to be NULL terminated, however if it is the output will be NULL terminated as well.

Details

Parameters

`[in,out] pairingCode`	On input, the pairing code string to be normalized. On output, The normalized string. It is not necessary for the string to be NULL terminated.
`[in,out] pairingCodeLen`	On input, the length of the pairing code string, not including any NULL terminator character. On output, the length of the normalized string.

PairingCodeCharToInt

int PairingCodeCharToInt(
  char ch
)

Convert a Weave pairing code character to an integer value in the range 0..31.

Note that this function is case-insensitive.

Details

Parameters

[in] ch

The character to be converted.

Returns

An integer value corresponding to the specified pairing code character, or -1 if ch is not a valid character.

PairingCodeToInt

WEAVE_ERROR PairingCodeToInt(
  const char *pairingCode,
  size_t pairingCodeLen,
  uint64_t & val
)

Decode a Weave pairing code as an integer value.

The function parses the initial characters of a Weave pairing code string as a big-endian, base-32 numeral and returns the resultant value as an unsigned integer. The input string can be any length >= 2 so long as the decoded integer fits within a uint64_t.

No attempt is made to verify the Verhoeff check character (see VerifyPairingCode()).

Details

Parameters

`[in] pairingCode`	The pairing code string to be decoded. This string does not need to be NULL terminated.
`[in] pairingCodeLen`	The length of the pairing code string, not including any NULL terminator character. Must be >= 2.
`[out] val`	The decoded integer value.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If pairingCodeLen is < 2, or the supplied pairing code string contains an invalid character, or the integer value encoded in the pairing code exceeds the max value that can be stored in a uint64_t.

VerifyPairingCode

WEAVE_ERROR VerifyPairingCode(
  const char *pairingCode,
  size_t pairingCodeLen
)

Verify a Weave pairing code against its check character.

Details

Parameters

`[in] pairingCode`	The pairing code string to be checked. This string does not need to be NULL terminated.
`[in] pairingCodeLen`	The length of the pairing code string, not including any NULL terminator character. Must be >= 2.

Return Values

`WEAVE_NO_ERROR`	If the method succeeded.
`WEAVE_ERROR_INVALID_ARGUMENT`	If pairingCodeLen is < 2, or the initial characters of the pairing code are not consistent with the value of the check character.