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)
Generate a random pairing code.
IntToPairingCode(uint64_t val, uint8_t pairingCodeLen, char *outBuf)
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)
Generates a Kryptonite pairing code string given a Kryptonite device id.
KryptonitePairingCodeToDeviceId(const char *pairingCode, uint64_t & deviceId)
Returns the device ID encoded in Kryptonite pairing code.
NevisDeviceIdToPairingCode(uint64_t deviceId, char *pairingCodeBuf, size_t pairingCodeBufSize)
Generates a Nevis pairing code string given a Nevis device id.
NevisPairingCodeToDeviceId(const char *pairingCode, uint64_t & deviceId)
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)
Decode a Weave pairing code as an integer value.
VerifyPairingCode(const char *pairingCode, size_t pairingCodeLen)
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.