Skip to main content

​
Utils API

The Utils API provides utility functions for text processing, display value management, hardware pin control, and system operations.

​
Display text management

​
UtilsAbstractDisplayValue_t

Structure for managing scrolling text on displays.
​
text
char[255]
Text buffer to display
​
index
uint8_t
Current display position index
​
length
uint8_t
Length of text
​
status
uint8_t
Active status: 0 = inactive, 1 = active
​
timeout
int8_t
Display timeout in iterations (-1 = indefinite)

​
UtilsDisplayValueInit

Initializes a display value structure. 
UtilsAbstractDisplayValue_t UtilsDisplayValueInit(
    char *text,
    uint8_t timeout
);
​
text
char *
Text string to display
​
timeout
uint8_t
Display timeout in iterations
​
returns
UtilsAbstractDisplayValue_t
Initialized display value structure

​
String functions

​
UtilsStricmp

Case-insensitive string comparison. 
int8_t UtilsStricmp(const char *str1, const char *str2);
​
returns
int8_t
0 if strings match (case-insensitive), non-zero otherwise

​
UtilsStrncpy

Safe string copy with null termination. 
char * UtilsStrncpy(char *dest, const char *src, size_t n);
​
dest
char *
Destination buffer
​
src
const char *
Source string
​
n
size_t
Maximum characters to copy

​
UtilsNormalizeText

Normalizes text by removing extended characters and truncating. 
void UtilsNormalizeText(
    char *output,
    const char *input,
    uint16_t maxLength
);
​
output
char *
Output buffer
​
input
const char *
Input text to normalize
​
maxLength
uint16_t
Maximum output length
This function transliterates Unicode characters to ASCII equivalents for display compatibility.

​
UtilsRemoveSubstring

Removes first occurrence of substring from a string. 
void UtilsRemoveSubstring(char *str, const char *substr);

​
UtilsCharIndex

Finds first occurrence of character in string. 
int16_t UtilsCharIndex(char *str, uint8_t character);
​
returns
int16_t
Index of character, or -1 if not found

​
Conversion functions

​
UtilsStrToHex

Converts hex string to byte value. 
unsigned char UtilsStrToHex(char *str);
Example: 
unsigned char value = UtilsStrToHex("FF"); // Returns 0xFF

​
UtilsStrToInt

Converts string to integer. 
uint8_t UtilsStrToInt(char *str);

​
UtilsConvertCmToIn

Converts centimeters to inches. 
uint8_t UtilsConvertCmToIn(uint8_t cm);

​
Unicode and text encoding

​
UtilsGetUnicodeByteLength

Returns byte length of a UTF-8 character. 
uint8_t UtilsGetUnicodeByteLength(uint8_t firstByte);
​
returns
uint8_t
Number of bytes in UTF-8 character (1-4)

​
UtilsTransliterateUnicodeToASCII

Transliterates Unicode character to ASCII equivalent. 
char * UtilsTransliterateUnicodeToASCII(uint32_t unicodeChar);
​
unicodeChar
uint32_t
Unicode codepoint (e.g., 0xC3A4 for ‘ä’)
​
returns
char *
ASCII transliteration or empty string
Supported characters:
  • Latin extended (À-ÿ) → ASCII equivalents
  • Cyrillic (А-я) → Romanized equivalents
  • Special symbols (–, ’, ’, …)
Example: 
char *ascii = UtilsTransliterateUnicodeToASCII(0xC3A4); // Returns "a" for 'ä'

​
UtilsTransliterateExtendedASCIIToASCII

Transliterates extended ASCII to standard ASCII. 
char * UtilsTransliterateExtendedASCIIToASCII(uint32_t extendedChar);

​
UtilsConvertCyrillicUnicodeToExtendedASCII

Converts Cyrillic Unicode to extended ASCII. 
unsigned char UtilsConvertCyrillicUnicodeToExtendedASCII(uint32_t unicodeChar);

​
Hardware control

​
UtilsSetPinMode

Configures pin as input or output. 
void UtilsSetPinMode(uint8_t pin, uint8_t mode);
​
pin
uint8_t
Pin number
​
mode
uint8_t
0 = output, 1 = input

​
UtilsSetRPORMode

Configures remappable peripheral pin. 
void UtilsSetRPORMode(uint8_t pin, uint16_t mode);
​
pin
uint8_t
RPOR pin number (0-31)
​
mode
uint16_t
Peripheral function code

​
System functions

​
UtilsGetBoardVersion

Returns hardware board version. 
uint8_t UtilsGetBoardVersion();
​
returns
uint8_t
Board version (1 or 2)

​
UtilsReset

Performs software reset. 
void UtilsReset();
This immediately resets the microcontroller. Ensure all critical operations are complete before calling.

​
UtilsGetMinByte

Finds minimum byte value in array. 
uint8_t UtilsGetMinByte(uint8_t *array, uint8_t size);

​
Bit manipulation macros

// Check if bit is set
UTILS_CHECK_BIT(var, pos)

// Set a bit
UTILS_SET_BIT(var, pos)

// Clear a bit
UTILS_CLEAR_BIT(var, pos)

// Unpack 8-bit BCD
UTILS_UNPACK_8BCD(bcd)
Example: 
uint8_t flags = 0x00;
flags = UTILS_SET_BIT(flags, 3);    // Set bit 3
if (UTILS_CHECK_BIT(flags, 3)) {     // Check if bit 3 is set
    // Bit is set
}
flags = UTILS_CLEAR_BIT(flags, 3);  // Clear bit 3

​
Constants

#define UTILS_DISPLAY_TEXT_SIZE 255  // Maximum display text length
#define UTILS_MAX_RPOR_PIN 31        // Maximum RPOR pin number
#define UTILS_PIN_TEL_MUTE 0         // Telephone mute pin
#define UTILS_PIN_TEL_ON 1           // Telephone on pin

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us