Utils

The st.utils library contains miscellaneous Lua helper functions.

st.utils.get_print_safe_string(str)

Print binary string as ascii hex

Parameters: str (str) –
Returns: ascii hex string
Return type: str

st.utils.bytes_to_hex_string(str)

convert binary string as ascii hex

Parameters: str (str) –
Returns: ascii hex string
Return type: str

st.utils.stringify_table(val, name, multi_line)

Convert value to string

Parameters

val (table) – Value to stringify
name (str) – Print a name along with value [Optional]
multi_line (boolean) – use newlines to provide a more easily human readable string [Optional]

st.utils.merge(target_table, template)

Recursively merge all fields of template not already present in target_table.

Parameters

target_table (table) – table into which to merge template
template (table) – table to merge into target_table

Returns

target_table

Return type

table

st.utils.update(target_table, template)

Recursively update all fields of target_table that are common and present in template.

Parameters

target_table (table) – table in which to update common fields from template
template (table) – table from which to update common fields in target_table

Returns

target_table

Return type

table

st.utils.clamp_value(val, min, max)

Force a value to fall between a min and max

Parameters

val (number) – the value to be clamped
min (number) – the minimum value to be returned
max (number) – the maximum value to be returned

st.utils.round(val)

Round a number to the nearest integer (.5 rounds up)

Parameters: val (number) – the value to be rounded
Returns: the rounded value
Return type: number

st.utils.serialize_int(value, width, signed, little_endian)

Serialize an integer into a bytestring.

Parameters

value (number) – value to write
width (number) – integer width in bytes
signed (boolean) – true if signed, false if unsigned
little_endian (boolean) – true if little endian, false if big endian

Returns

serialized integer as byte string

Return type

str

st.utils.deserialize_int(buf, width, signed, little_endian)

Deserialize an integer from the passed string.

Parameters

buf (str) – bytestring from which to deserialize an integer
width (number) – integer width in bytes
signed (boolean) – true if signed, false if unsigned
little_endian (boolean) – true if little endian, false if big endian

Returns

deserialized integer

Return type

number

st.utils.hsv_to_rgb(hue, saturation)

Converts Hue/Saturation to Red/Green/Blue

Parameters

hue (number) – hue in range [0,1]
saturation (number) – saturation in range[0,1]

Returns

equivalent red, green, blue with each color in range [0,1]

Return type

number or number or number

st.utils.rgb_to_hsv(red, green, blue)

Converts Red/Green/Blue to Hue/Saturation

Parameters

red (number) – red in range [0,1]
green (number) – green in range [0,1]
blue (number) – blue in range [0,1]

Returns

equivalent hue, saturation, level with each value in range [0,1]

Return type

number or number or number

st.utils.xy_to_rgb(x, y, Y)

Convert from x/y/Y to Red/Green/Blue

Parameters

x (number) – x axis non-negative value
y (number) – y axis non-negative value
Y (number) – Y tristimulus value

st.utils.rgb_to_xy(red, green, blue)

Convert from Red/Green/Blue to x/y/Y

Parameters

red (number) – red in range [0,1]
green (number) – green in range [0,1]
blue (number) – blue in range [0,1]

st.utils.safe_hsv_to_xy(hue, saturation)

Safe convert from Hue/Saturation to x/y/Y

If hue or saturation is missing 0 is applied

Parameters

hue (number) – red in range [0,100]%
saturation (number) – green in range [0,100]%

st.utils.safe_xy_to_hsv(x, y, Y)

Convert from x/y/Y to Hue/Saturation

If every value is missing then [x, y, Y] = [0, 0, 1]

Parameters

x (number) – red in range [0x0000, 0xFFFF]
y (number) – green in range [0x0000, 0xFFFF]
Y (number) – blue in range [0x0000, 0xFFFF]

st.utils.hsl_to_rgb(hue, saturation, lightness)

Convert from Hue/Saturation/Lightness to Red/Green/Blue

If lightness is missing, default to 50%.

Parameters

hue (number) – hue in the range [0,100]%
saturation (number) – saturation in the range [0,100]%
lightness (number) – lightness in the range [0,100]%, or nil

st.utils.rgb_to_hsl(red, green, blue)

Convert from red, green, blue to hue, saturation, lightness.

Parameters

red (number) – red component in the range [0,255]
green (number) – green component in the range [0,255]
blue (number) – blue component in the range [0,255]

Returns

equivalent hue, saturation, lightness vector with each component in the range [0,100]

Return type

number or number or number

st.utils.c_to_f(celsius)

Convert celsius to fahrenheit.

Parameters: celsius (number) – temperature in celsius
Returns: integer fahrenheit value
Return type: number

st.utils.f_to_c(fahrenheit)

Convert fahrenheit to celsius.

Parameters: fahrenheit (number) – temperature in fahrenheit
Returns: integer celsius value
Return type: number

st.utils.deep_copy(val)

Copy a table and all it’s values recursively

Parameters: val (table) – the table to copy
Returns: the copied table
Return type: table

st.utils.rsort(tbl)

Reverse-sort the passed table.

Parameters: tbl (table) – (in/out) table to be reverse sorted
Returns: reverse-sorted table
Return type: table

st.utils.pairs_by_key(t, f)

Table iterator for traversal by ordered keys.

Parameters

t (table) – over which to iterate
f (function) – optional key comparison function

Returns

table iterator

Return type

function

st.utils.rkeys(t)

Table iterator for traversal by reverse-sorted keys.

Parameters: t (table) – over which to iterate
Returns: table iterator
Return type: function

st.utils.fkeys(t)

Table iterator for traversal by forward-sorted keys.

Parameters: t (table) – over which to iterate
Returns: table iterator
Return type: function

st.utils.pairs_by_value(t, f)

Table iterator for traversal by ordered values.

Parameters

t (table) – over which to iterate
f (value) – required value comparison function

Returns

table iterator

Return type

function

st.utils.rvalues(t)

Table iterator for traversal by reverse-sorted values.

Parameters: t (table) – over which to iterate
Returns: table iterator
Return type: function

st.utils.fvalues(t)

Table iterator for traversal by forward-sorted values.

Parameters: t (table) – over which to iterate
Returns: table iterator
Return type: function

st.utils.camel_case(str)

Convert the passed string to camelCase.

Parameters: str (str) – string to convert
Returns: camelCase version of the string
Return type: str

st.utils.pascal_case(str)

Convert the passed string to PascalCase.

Parameters: str (str) – string to convert
Returns: PascalCase version of the string
Return type: str

st.utils.snake_case(str)

Convert the passed string to snake_case.

Parameters: str (str) – string to convert
Returns: snake_case version of the string
Return type: str

st.utils.screaming_snake_case(str)

Convert the passed string to SCREAMING_SNAKE_CASE.

Parameters: str (str) – string to convert
Returns: SCREAMING_SNAKE_CASE version of the string
Return type: str

st.utils.verify_type(value, v_type, arg_name)

Throw an error if the provided value isn’t of the provided type

Parameters

value (any) – The value to check the type of
v_type (str) – the expected value of type(value)
arg_name (str or nil) – If present, used in generated error message

st.utils.table_size(t)

Return number of elements stored in a table

Parameters: t (table) – The table which length needs to be calculated
Returns: Count of elements in table
Return type: number

st.utils.generate_uuid_v4()

Generate a version 4 uuid as a string

Return type: str

st.utils.bitify(byte_string)

Turn a byte string into an array of bits with the most significant bit of each byte listed first

Parameters: byte_string (str) – the byte string to convert to bits
Returns: an array of bits representing the byte string
Return type: list[number]

st.utils.bit_list_to_int(bit_list)

Turn an array of bits into a number

Parameters: bit_list (list[number]) – An array of bits (1 or 0)
Returns: the numeric value of the bit_list
Return type: number

st.utils.bit_list_to_byte_str(bit_list)

Convert a bit list to a byte string

Parameters: bit_list (list[number]) – An array of bits (1 or 0) must be a length multiple of bytes
Returns: the byte list of the bit array
Return type: str

st.utils.mole_per_cubic_meter_to_ppm(value)

Convert a gas concentration given in moles per cubic meter [mol/m3] to value in part per million [ppm]

Parameters: value (number) – Concentration of gas [mol/m3]
Returns: Concentration of gas [ppm]
Return type: str

st.utils.log_func_wrapper(func, func_name, log_level)

Wrap a function that will log all calls to the function along with the arguments

This will take a function and return a function that will perform the same actions as the passed in function but also log every call to the function along with the arguments passed in. Arguments will be expanded to readable strings when possible, but will be truncated to 25 characters except when logged at the LOG_LEVEL_TRACE level when full arguments will be logged regardless of length.

Parameters

func (function) – the function to be wrapped
func_name (str) – the name of the function to include in the logs
log_level (str) – the level you want the function logging to print at, defaults to LOG_LEVEL_DEBUG

Returns

The new function that will perform the same behavior, but also log calls

Return type

function

st.utils.backoff_builder(max, inc, rand)

Build an exponential backoff time value generator (function)

Parameters

max (number) – the maximum wait interval (not including rand factor)
inc (number) – the rate at which to exponentially back off
rand (number) – a randomization range of (-rand, rand) to be added to each interval

Returns

the backoff generator that will return a new value each time it is called.

Return type

function

st.utils.signed_to_unsigned(value, size)

Convert a value from a 2s complement signed integer to an unsigned integer

Parameters

value (number) – the signed value
size (number) – the size of the value (in bytes)

Returns

the converted value

Return type

number

st.utils.unsigned_to_signed(value, size)

Convert an unsigned integer into a 2s complement signed integer

Parameters

value (number) – the unsigned integer value
size (number) – the size of the value (in bytes)

Returns

the converted value

Return type

number