Utility Functions

Akenza provides utility functions which contain commonly used functionality for e.g. converting hex strings into a bit string and vice-versa.

These functions are useful in device types if the uplink payload is hex or base64 encoded or even a bit string representation.

Bit Utility Functions

Bit utility functions provide already implemented logic to convert and manipulate bit represenations to numbers or hexadecimal strings and vice-versa.

Hex to Bits

Usage

Bits.hexToBits(hex: string): string

Examples

Bits.hexToBits('DEADBEEF') -> '11011110101011011011111011101111'

Bits.hexToBits('0xaa') -> '10101010'

Details

This function converts a hex string to a bit string in big endian format.

The hex string can be prefixed with 0x but it is not required.

Throws an error if the hex string does not contain valid hexadecimal characters (0-9a-fA-F).

Bits to Hex

Usage

Bits.bitsToHex(bits: string): string

Examples

Bits.bitsToHex('11011110101011011011111011101111') -> 'DEADBEEF'

Bits.bitsToHex('10101010') -> 'AA'

Details

This function converts a bit string into a hex string. The resulting hex string does not contain the prefix 0x.

The bit representation has to be in big endian format. Otherwise the results will differ.

Throws an error if the bit string is invalid (it may only consist of 1s and 0s).

Base64 to Bits

Usage

Bits.base64ToBits(base64: string): string

Examples

Bits.base64ToBits('Zm9vIA==') -> '01100110011011110110111100100000'

Bits.base64ToBits('YmFy') -> '011000100110000101110010'

Details

This function converts a base64 encoded string into a bit string.

Throws an error if the provided bas64 string is invalid. More info about valid base64 characters.

Bits to Base64

Usage

Bits.bitsToBase64(bits: string): string

Examples

Bits.bitsToBase64('01100110011011110110111100100000') -> 'Zm9vIA=='

Bits.bitsToBase64('011000100110000101110010') -> 'YmFy'

Details

This function converts a bit string into a base64 encoded string.

Throws an error if the provided bit string could not successfully be converted to base 64 e.g. the resulting string will contain invalid base64 characters. More info about valid base64 characters.

Bits to Signed Integer

Usage

Bits.bitsToSigned(bits: string): number

Examples:

Bits.bitsToSigned('1001') -> -7

Bits.bitsToSigned('0110') -> 6

Details

This function converts a bit string representation of an unsigned integer into an integer.

The bit string representation has to be in big endian format. Otherwise the results will differ.

Throws an error if the bit string is invalid (it may only consist of 1s and 0s).

Bits to Unsigned Integer

Usage

Bits.bitsToUnsigned(bits: string): number

Examples:

Bits.bitsToUnsigned('1001') -> 9

Bits.bitsToUnsigned('0110') -> 6

Details

This function converts a bit string representation of a signed integer into an integer.

The bit string representation has to be in big endian format. Otherwise the results will differ.

Throws an error if the bit string is invalid (it may only consist of 1s and 0s).

Number to Bits

Usage

Bits.numberToBits(value: number, cutOff?: number): string

The function can be invoked with one or two arguments.

The second argument is optional and can either be null or left out completely. If the resulting bit string representation would be smaller than the specified cut off amount, the full bit string representation will be returned, without padding 0s to make up the difference.

Examples:

Bits.numberToBits(123) -> '1111011'

Bits.numberToBits(123, 4) -> '1011'

Bits.numberToBits(123, 16) -> '1111011'

Details

This function converts a number into an unsigned bit-string representation. If the cutOff argument is specified, the resulting string is cut off after the specified amount of bits starting at the LSB. As the resulting bit string is a big endian representation of the number, the cut off point starts from the right hand end of the string up until the specified cut off amount.

Throws an error if an invalid number was provided either for the first or second argument (if present).

Hex Utility Functions

Hex utility functions provide already implemented logic to convert and manipulate hex representations to numbers or byte arrays and vice-versa.

Hex to Bytes

Usage

Hex.hexToBytes(hex: string): number[]

Examples

Hex.hexToBytes('DEADBEEF') -> [222, 173, 190, 239]

Hex.hexToBytes('0xf00ba8') -> [240, 11, 168]

Details

This function converts a hex string into a JS byte array. JS bytes are unsigned integers ranging from 0 - 255.

The hex string can be prefixed with 0x but it is not required.

Throws an error if the hex string does not contain valid hexadecimal characters (0-9a-fA-F).

Bytes to Hex

Usage

Hex.bytesToHex(bytes: number[]): string

Examples

Hex.bytesToHex([222, 173, 190, 239]) -> 'DEADBEEF'

Hex.bytesToHex([240, 11, 168]) -> 'F00BA8'

Details

This function converst an array of JS bytes (numbers from 0 - 255) to a hex string.

Throws an error if the bytes array contains values below 0 or above 255.

Hex Little Endian to Big Endian Number

Usage

Hex.hexLittleEndianToBigEndian(hex: string, signed: boolean): number

Examples:

Hex.hexLittleEndianToBigEndian('AA', false) -> 170

Hex.hexLittleEndianToBigEndian('0xaa', true) -> -86

Details

This function converts the hex string in little endian forma to a big endian number.

The signed param is used to indicate whether the hex representation is a signed or unsigned little endian.

The hex string can be prefixed with 0x but it is not required.

Throws an error if the hex string does not contain valid hexadecimal characters (0-9a-fA-F).

Throws an error if the signed argument is not a valid boolean.