This is the multi-page printable view of this section. Click here to print...

For suitable output, we recommend to use Google Chrome (15+) or Microsoft Edge (79+).

As of 2025-09-10

TWENETutils - TWENET Utility

A library that encapsulates general algorithms and peripheral procedures.

1: utils.h

2: Timer Library

3: fprintf Library

This library includes general algorithms and peripheral procedures.

TWENETutils - TWENET Utility

This library includes general algorithms and peripheral procedures. It corresponds to libTWENETutils.a.

Refer to the TWELITE NET API Reference “Utils Reference, etc.”

1 - utils.h

Start Functions: main(), WarmMain()

Macros and functions available by including utils.h.

`utils.h`

This section introduces the macros and functions available by including utils.h.

`S_OCTET(x)`

Writes one byte to memory.

uint8 *q = &sTx.au8Data[0];

S_OCTET(0x12);
S_BE_WORD(0x1234);
S_BE_DWORD(0x12345678);

Declare uint8 *q as a local variable and use it as a pointer to the memory area where you want to write data. q++ is executed after the assignment operator is evaluated.

`S_BE_WORD(x)`

Writes two bytes to memory.

uint8 *q = &sTx.au8Data[0];

S_OCTET(0x12);　
S_BE_WORD(0x1234);
S_BE_DWORD(0x12345678);

Declare uint8 *q as a local variable and use it as a pointer to the memory area where you want to write data. q+=2 is executed after the assignment operator is evaluated.

BE stands for Big Endian, and LE for Little Endian.

`S_BE_DWORD(x)`

Writes four bytes to memory.

uint8 *q = &sTx.au8Data[0];

S_OCTET(0x12);　
S_BE_WORD(0x1234);
S_BE_DWORD(0x12345678);

Declare uint8 *q as a local variable and use it as a pointer to the memory area where you want to write data. q+=4 is executed after the assignment operator is evaluated.

BE stands for Big Endian, and LE for Little Endian.

`G_OCTET()`

Reads one byte from memory and stores the value in a uint8 type variable.

uint8 *p = &sRx.au8Data[0];

uint8 u8data1 = OCTET();　
uint16 u16data2 = G_BE_WORD();
uint32 u32data3 = G_BE_DWORD();

Declare uint8 *p as a local variable and use it as a pointer to the memory area you want to read data from. p++ is executed after the = operator is evaluated.

`G_BE_WORD()`

Reads two bytes from memory and stores the value in a uint16 type variable.

uint8 *p = &sRx.au8Data[0];

uint8 u8data1 = OCTET();　
uint16 u16data2 = G_BE_WORD();
uint32 u32data3 = G_BE_DWORD();

Declare uint8 *p as a local variable and use it as a pointer to the memory area you want to read data from. p+=2 is executed after the = operator is evaluated.

BE stands for Big Endian, and LE for Little Endian.

`G_BE_DWORD()`

Reads four bytes from memory and stores the value in a uint32 type variable.

uint8 *p = &sRx.au8Data[0];

uint8 u8data1 = OCTET();　
uint16 u16data2 = G_BE_WORD();
uint32 u32data3 = G_BE_DWORD();

Declare uint8 *p as a local variable and use it as a pointer to the memory area you want to read data from. p+=4 is executed after the = operator is evaluated.

BE stands for Big Endian, and LE for Little Endian.

`ENCODE_VOLT(x)`

This function converts a value from 2000 to 3600 into an 8-bit value.

1.95V to 2.80V is in 5mV increments.
2.81V to 3.65V is in 10mV increments.

// utils.h definition
#define ENCODE_VOLT(m) \
	(m < 1950 ? 0 : \
		(m > 3650 ? 255 : \
			(m <= 2802 ? ((m-1950+2)/5) : ((m-2800-5)/10+171)) ))
...
uint16 u16Volt = 2860;
uint8 u8Volt_enc = ENCODE_VOLT(u16Volt);
uint16 u16Volt_dec = DECODE_VOLT(u8Volt_Enc);

Values from 2000 to 2800 are assigned to an 8-bit value in increments of 5, and values from 2800 onwards are assigned in increments of 10.

`DECODE_VOLT(x)`

This function converts the 8-bit value obtained from ENCODE_VOLT() back to its original value.

1.95V to 2.80V is in 5mV increments.
2.81V to 3.65V is in 10mV increments.

// utils.h definition
#define DECODE_VOLT(i) \
	(i <= 170 ? (1950+i*5) : (2800+(i-170)*10) )
...
uint16 u16Volt = 2860;
uint8 u8Volt_enc = ENCODE_VOLT(u16Volt);
uint16 u16Volt_dec = DECODE_VOLT(u8Volt_Enc);

Values from 2000 to 2800 are assigned to an 8-bit value in increments of 5, and values from 2800 onwards are assigned in increments of 10.

`vPortAsInput(c)`

Sets port c as input.

#define vPortAsInput(c) vAHI_DioSetDirection(1UL << (c), 0)

`vPortAsOutput(c)`

Sets port c as output.

#define vPortAsOutput(c) vAHI_DioSetDirection(0, 1UL << (c))

`vPortSetHi(c)`

Sets port c to a high state.

#define vPortSetHi(c) vAHI_DioSetOutput(1UL << (c), 0)

`vPortSetLo(c)`

Sets port c to a low state.

#define vPortSetLo(c) vAHI_DioSetOutput(0, 1UL << (c))

`vPortSet_TrueAsLo(c, s)`

Sets port c to Lo if s is TRUE, and to Hi if s is FALSE.

#define vPortSet_TrueAsLo(c, s)  vAHI_DioSetOutput((s) ? \
    0 : 1UL << (c), s ? 1UL << (c) : 0)

`bPortRead(c)`

Reads port c. Returns TRUE if the level is low.

#define bPortRead(c) ((u32AHI_DioReadInput() & \
    (1UL<<(c))) ? FALSE : TRUE)

`u32PortReadBitmap()`

Reads port c. Returns TRUE if the level is low.

#define u32PortReadBitmap() (u32AHI_DioReadInput())

A value of 1 in the bitmap represents Hi, and 0 represents Lo.

`bPortCheckBitmap(bitmap, c)`

This function returns TRUE if the bit corresponding to port c in the read bitmap is at a low level.

#define bPortCheckBitmap(bitmap, c) \
    (bitmap & (1UL<<(c))) ? FALSE : TRUE)

`vPortDisablePullup(c)`

This function disables the pull-up for port c.

#define vPortDisablePullup(c) vAHI_DioSetPullup(0x0, 1UL << (c))

`_C`

This macro is used to define a scope within a switch statement. It is written as _C { … }.

#define _C if(1)

// for example

switch(c) {
case 1:
  _C {
    uint8 u8work;
    ; // work
  } break;
default:
}

`LB`

This is a newline string literal (CRLF).

Since it is a two-byte string literal, it cannot be used with vPutChar().

#define LB "\r\n"

`vWait()` function

This function waits for a specified amount of time using a loop.

void vWait(uint32 c) {
	static volatile uint32 u32ct = 0;
	while (c-- > 0)
		u32ct++;
}

The process is as described in the source code.

`vAnalogueConfig()`, `vAnalogueDisable()`

These functions bundle the procedures for initializing and stopping the ADC function. They are intended for compatibility with existing code.

void vAnalogueConfig(void) {
#if defined(JN516x)
	if (!bAHI_APRegulatorEnabled()) {
		vAHI_ApConfigure(E_AHI_AP_REGULATOR_ENABLE,
				E_AHI_AP_INT_DISABLE,
				E_AHI_AP_SAMPLE_4,
				E_AHI_AP_CLOCKDIV_1MHZ,
				E_AHI_AP_INTREF);

		while (!bAHI_APRegulatorEnabled())
			;
	}
#elif defined(CPU_JN518X)
#endif

void vAnalogueDisable(void) {
#if defined(JN516x)
	vAHI_ApConfigure(E_AHI_AP_REGULATOR_DISABLE,
			E_AHI_AP_INT_DISABLE,
			E_AHI_AP_SAMPLE_4,
			E_AHI_AP_CLOCKDIV_1MHZ,
			E_AHI_AP_INTREF);
#elif defined(CPU_JN518X)
#endif
}

Other Macro Definitions

// 64bit mac address
#define MAC_EXT_ADDR_TO_64BIT(ext) ((uint64)(ext.u32L) | (((uint64)(ext.u32H)) << 32))

// TIME COMPARE
#define u32TimeDiff(ref, now) (now - ref < 0x7FFFFFFF ? now - ref : )

// IO settings
#define vPortSetHi(c) vAHI_DioSetOutput(1UL << (c), 0)
#define vPortSetLo(c) vAHI_DioSetOutput(0, 1UL << (c))
#define vPortSet_TrueAsLo(c, s)  vAHI_DioSetOutput((s) ? 0 : 1UL << (c), s ? 1UL << (c) : 0)
#define vPortAsInput(c) vAHI_DioSetDirection(1UL << (c), 0)
#define vPortAsOutput(c) vAHI_DioSetDirection(0, 1UL << (c))
#define bPortRead(c) ((u32AHI_DioReadInput() & (1UL<<(c))) ? FALSE : TRUE) // Lo as True
#define u32PortReadBitmap() (u32AHI_DioReadInput())
#define bPortCheckBitmap(bitmap, c) ((bitmap & (1UL<<(c))) ? FALSE : TRUE)
#define vPortDisablePullup(c) vAHI_DioSetPullup(0x0, 1UL << (c))

#if defined(JN516x) || defined(CPU_JN518X)
#define PORT_KIT_SW1 2
#define PORT_KIT_SW2 3
#define PORT_KIT_SW3 10
#define PORT_KIT_SW4 9
#define PORT_KIT_LED1 17
#define PORT_KIT_LED2 13
#define PORT_KIT_LED3 12
#define PORT_KIT_LED4 11
#endif

#define PORT_KIT_SW1_MASK (1UL << PORT_KIT_SW1)
#define PORT_KIT_SW2_MASK (1UL << PORT_KIT_SW2)
#define PORT_KIT_SW3_MASK (1UL << PORT_KIT_SW3)
#define PORT_KIT_SW4_MASK (1UL << PORT_KIT_SW4)
#define PORT_KIT_SW_ALL2_MASK (PORT_KIT_SW1_MASK | PORT_KIT_SW2_MASK)
#define PORT_KIT_SW_ALL4_MASK (PORT_KIT_SW1_MASK | PORT_KIT_SW2_MASK | PORT_KIT_SW3_MASK | PORT_KIT_SW4_MASK)

#define PORT_KIT_LED1_MASK (1UL << PORT_KIT_LED1)
#define PORT_KIT_LED2_MASK (1UL << PORT_KIT_LED2)
#define PORT_KIT_LED3_MASK (1UL << PORT_KIT_LED3)
#define PORT_KIT_LED4_MASK (1UL << PORT_KIT_LED4)
#define PORT_KIT_LED_ALL2_MASK (PORT_KIT_LED1_MASK | PORT_KIT_LED2_MASK)
#define PORT_KIT_LED_ALL4_MASK (PORT_KIT_LED1_MASK | PORT_KIT_LED2_MASK | PORT_KIT_LED3_MASK | PORT_KIT_LED4_MASK)

// UART related
#define WAIT_UART_OUTPUT(P) SERIAL_vFlush(P)

// IO clock (on JN514x, IO runs at 16Mhz regardless of CPU clock.
#if defined(JN516x)
#define u32IO_FREQ_HZ 16000000UL
#elif defined(CPU_JN518X)
//#define u32IO_FREQ_HZ 32000000UL
#define u32IO_FREQ_HZ 16000000UL
#endif

void vAnalogueConfig(void);
void vAnalogueDisable(void);

void vWait(uint32 c);

2 - Timer Library

Timer library

Introducing the Timer library.

Timer Library

`tsTimerContext`

A structure for configuration used by the Timer library.

Clear it to 0.
Ensure it is statically allocated.

Type	Name	Explanation
`uint8`	`u8Device`	Specifies the timer device (`E_AHI_DEVICE_TIMER0`..4).
`uint16`	`u16Hz`	Specifies the timer frequency in Hz.
`uint8`	`u8PreScale`	Sets the prescaler for the 16MHz clock.
`bool_t`	`bPWMOut`	If `TRUE`, performs PWM output.
`bool_t`	`bDisableInt`	If `TRUE`, disables interrupts.

`vTimerConfig()`

Explanation

Initializes the Timer.

Arguments

Type	Name	Description
`tsTimerContext`	`psTC`	The timer configuration structure.

Return Value

None.

Sample

tsTimerContext sTimerApp; // global or static allocation

// set 64ticks/sec
memset(&sTimerApp, 0, sizeof(tsTimerContext));
sTimerApp.u8Device = E_AHI_DEVICE_TIMER0;
sTimerApp.u16Hz = 64;
sTimerApp.u8PreScale = 4; // 15625ct@2^4

`vTimerStart()`

Explanation

Starts the Timer.

This function can also be called for a Timer that has already been started. It is used when changing the duty cycle, etc.

Arguments

Type	Name	Description
`tsTimerContext`	`psTC`	The timer configuration structure.

Return Value

None.

Sample

// initialize and start
vTimerConfig(&sTimerApp); // initialize
vTimerStart(&sTimerApp); // start

// change duty
sTimerPWM.u16Duty = 256; // set new duty ratio
vTimerStart(&sTimerPWM); // just start again to change duty

`vTimerStop()`

Explanation

Stops the operation of the Timer.

Arguments

Type	Name	Description
`tsTimerContext`	`psTC`	The timer configuration structure.

Return Value

None.

Sample

// just stop the timer
vTimerStop(&sTimerApp);
...
// restart
vTimerStart(&sTimerApp);
...
// now, disable timer completely
vTimerStop(&sTimerApp);
vTimerDisable(&sTimerApp);

`vTimerDisable()`

This function destroys the Timer.

Arguments

Type	Name	Description
`tsTimerContext`	`psTC`	The timer configuration structure.

Return Value

None.

Sample

// just stop the timer
vTimerStop(&sTimerApp);
...
// restart
vTimerStart(&sTimerApp);
...
// now, disable timer completely
vTimerStop(&sTimerApp);
vTimerDisable(&sTimerApp);

3 - fprintf Library

fprintf library

This is a simple implementation of fprintf.

`fprintf` Library

This is a simple implementation of fprintf.

{{< hint color=“info” >}} This library is provided for source code compatibility. For new implementations, it is recommended to use TWENETmcu/printf. {{< /hint >}}

Reference

TWENETmcu/printf - printf library (open source)
TWENETstgs - TWE_fprintf(), etc.

`tsFILE`

A structure that defines the output destination specified by vfPrintf() and vPutChar().

Members

Type	Name	Description
`uint8`	`u8Device`	Specifies the serial port (`E_AHI_UART_0` or `E_AHI_UART_1`).
`bool_t (*) (uint8 u8Device, uint8 u8Char)`	`bPutChar`	A function pointer for output. For the `SERIAL` library, `SERIAL_bTxChar()` is prepared, so specify that.

{% hint style=“info” %} SERIAL_bTxChar() puts the byte passed as u8Char into the FIFO queue within the SERIAL library.

By preparing your own output function, you can use this for outputting strings to destinations other than UART. {% endhint %}

Sample code

#include "serial.h"
#include "fprintf.h"

tsFILE sSerStream;
tsSerialPortSetup sSerPort;

void vSerialInit(uint32 u32Baud, tsUartOpt *pUartOpt) {
	// initialize sSerPort
	...
	SERIAL_vInit(&sSerPort);

	// for vfPrintf()
	sSerStream.bPutChar = SERIAL_bTxChar;
	sSerStream.u8Device = E_AHI_UART_0;
}

void vSerOut() {
    vfPrintf(&sSerStream, "HELLO!");
}

Here is an example of the character LCD output code.

#include "serial.h"
#include "fprintf.h"

tsFILE sLcdStream;

// handle LCD display
PUBLIC bool_t LCD_bTxChar(uint8 u8Device, uint8 u8Data) {
	int i;

	switch (u8Data) {
	case '\n':
	...
}

void vInitHardware() {
    /* Initialise the LCD */
    vLcdReset(3, 0);

    /* register for vfPrintf() */
    sLcdStream.bPutChar = LCD_bTxChar;
    sLcdStream.u8Device = 0xFF;
}

void vSomeOutput() {
    vfPrintf(&sLcdStream, "Hello World!\n");
}

`vfPrintf()`

Explanation

This function outputs to the destination specified by the tsFILE structure (UART) using printf format.

Arguments

Type	Name	Description
`tsFILE*`	`psStream`	Output destination
`const char *`	`pcFormat`	Output format
…		Variable arguments

Supported Formats

`s`	String
`d`	Integer (up to 32 bits)
`u`	Unsigned integer (up to 32 bits)
`x`	Hexadecimal. `a-f` are lowercase.
`X`	Hexadecimal. `A-F` are uppercase.
`b`	Bit sequence

Return Value

None.

Sample

void cbToCoNet_vMain(void) {
	while (!SERIAL_bRxQueueEmpty(sSerPort.u8SerialPort)) {
		int16 i16Char;
		i16Char = SERIAL_i16RxChar(sSerPort.u8SerialPort);
		vfPrintf(&sSerStream, "\n\r## [%c] --> ", i16Char);
	    SERIAL_vFlush(sSerStream.u8Device);
		...
	}
}

`vPutChar()`

Explanation

This function outputs one byte to the destination specified by the tsFILE structure (UART).

Arguments

Type	Name	Description
`tsFILE*`	`psStream`	Output destination
`uint8`	`u8Char`	Output byte

Return Value

None

Sample

#define IS_ASC(c) ((c) >= 0x20 && (c) <= 0x7e)

void cbToCoNet_vRxEvent(tsRxDataApp *pRx) {
	uint8 u8i;
	vfPrintf(&sSerStream, LB"RX(len=%d):[", pRx->u8Len);
	for (i = 0; i < pRx->u8Len; i++) {
		uint8 c = pRx->auData[i];
		vPutChar(&sSerStream, IS_ASC(c) ? c : '.');
	}
}

TWENETutils - TWENET Utility

TWENETutils - TWENET Utility

1 - utils.h

utils.h

S_OCTET(x)

S_BE_WORD(x)

S_BE_DWORD(x)

G_OCTET()

G_BE_WORD()

G_BE_DWORD()

ENCODE_VOLT(x)

DECODE_VOLT(x)

vPortAsInput(c)

vPortAsOutput(c)

vPortSetHi(c)

vPortSetLo(c)

vPortSet_TrueAsLo(c, s)

bPortRead(c)

u32PortReadBitmap()

bPortCheckBitmap(bitmap, c)

vPortDisablePullup(c)

_C

LB

vWait() function

vAnalogueConfig(), vAnalogueDisable()

Other Macro Definitions

2 - Timer Library

Timer Library

tsTimerContext

vTimerConfig()

Explanation

Arguments

Return Value

Sample

vTimerStart()

Explanation

Arguments

Return Value

Sample

vTimerStop()

Explanation

Arguments

Return Value

Sample

vTimerDisable()

Arguments

Return Value

Sample

3 - fprintf Library

fprintf Library

Reference

tsFILE

Members

Sample code

vfPrintf()

Explanation

Arguments

Supported Formats

Return Value

Sample

vPutChar()

Explanation

Arguments

Return Value

Sample

`utils.h`

`S_OCTET(x)`

`S_BE_WORD(x)`

`S_BE_DWORD(x)`

`G_OCTET()`

`G_BE_WORD()`

`G_BE_DWORD()`

`ENCODE_VOLT(x)`

`DECODE_VOLT(x)`

`vPortAsInput(c)`

`vPortAsOutput(c)`

`vPortSetHi(c)`

`vPortSetLo(c)`

`vPortSet_TrueAsLo(c, s)`

`bPortRead(c)`

`u32PortReadBitmap()`

`bPortCheckBitmap(bitmap, c)`

`vPortDisablePullup(c)`

`_C`

`LB`

`vWait()` function

`vAnalogueConfig()`, `vAnalogueDisable()`

`tsTimerContext`

`vTimerConfig()`

`vTimerStart()`

`vTimerStop()`

`vTimerDisable()`

`fprintf` Library

`tsFILE`

`vfPrintf()`

`vPutChar()`