openlcb_float16.h File Reference

IEEE 754 half-precision (float16) conversion utilities. More...

Go to the source code of this file.

Macros
#define	FLOAT16_POSITIVE_ZERO   0x0000
	float16 value representing positive zero (forward, stopped).
#define	FLOAT16_NEGATIVE_ZERO   0x8000
	float16 value representing negative zero (reverse, stopped).
#define	FLOAT16_NAN   0x7E00
	float16 NaN value (speed not available).
#define	FLOAT16_SIGN_MASK   0x8000
	Bit mask for the sign/direction bit (bit 15).
#define	FLOAT16_EXPONENT_MASK   0x7C00
	Bit mask for the 5-bit exponent field (bits 14-10).
#define	FLOAT16_MANTISSA_MASK   0x03FF
	Bit mask for the 10-bit mantissa field (bits 9-0).

Functions
uint16_t	OpenLcbFloat16_from_float (float value)
	Converts a 32-bit float to a float16 bit pattern.
float	OpenLcbFloat16_to_float (uint16_t half)
	Converts a float16 bit pattern to a 32-bit float.
uint16_t	OpenLcbFloat16_negate (uint16_t half)
	Flips the sign/direction bit of a float16 value and returns the result.
bool	OpenLcbFloat16_is_nan (uint16_t half)
	Returns true if the float16 bit pattern represents NaN (speed not available).
bool	OpenLcbFloat16_is_zero (uint16_t half)
	Returns true if the float16 bit pattern represents positive or negative zero.
uint16_t	OpenLcbFloat16_speed_with_direction (float speed, bool reverse)
	Encodes a speed magnitude and direction into a float16 bit pattern.
float	OpenLcbFloat16_get_speed (uint16_t half)
	Returns the speed magnitude from a float16 bit pattern (ignores direction).
bool	OpenLcbFloat16_get_direction (uint16_t half)
	Returns true if the direction bit is set (reverse).

Detailed Description

IEEE 754 half-precision (float16) conversion utilities.

Copyright

Copyright (c) 2026, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Encodes/decodes OpenLCB train speed as binary16. Sign bit = direction (0 forward, 1 reverse). All conversions use integer-only bit manipulation for embedded targets.

Author

Jim Kueneman

Date

28 Feb 2026

Macro Definition Documentation

FLOAT16_POSITIVE_ZERO

#define FLOAT16_POSITIVE_ZERO   0x0000

float16 value representing positive zero (forward, stopped).

FLOAT16_NEGATIVE_ZERO

#define FLOAT16_NEGATIVE_ZERO   0x8000

float16 value representing negative zero (reverse, stopped).

FLOAT16_NAN

#define FLOAT16_NAN   0x7E00

float16 NaN value (speed not available).

FLOAT16_SIGN_MASK

#define FLOAT16_SIGN_MASK   0x8000

Bit mask for the sign/direction bit (bit 15).

FLOAT16_EXPONENT_MASK

#define FLOAT16_EXPONENT_MASK   0x7C00

Bit mask for the 5-bit exponent field (bits 14-10).

FLOAT16_MANTISSA_MASK

#define FLOAT16_MANTISSA_MASK   0x03FF

Bit mask for the 10-bit mantissa field (bits 9-0).

Function Documentation

OpenLcbFloat16_from_float()

uint16_t OpenLcbFloat16_from_float ( float value )

extern

Converts a 32-bit float to a float16 bit pattern.

Rounds toward zero. Overflow is clamped. NaN produces FLOAT16_NAN.

Parameters

value

32-bit float to convert.

Returns

16-bit float16 bit pattern.

Algorithm:

1. Extract sign, exponent, mantissa from IEEE 754 single
2. Handle special cases: zero, NaN, infinity
3. Clamp overflow to max finite half value
4. Normal range: rebias exponent, truncate mantissa
5. Subnormal: shift mantissa into denormalized form
6. Underflow: flush to signed zero

* @param value 32-bit float to convert
* 

Returns

16-bit float16 bit pattern

OpenLcbFloat16_to_float()

float OpenLcbFloat16_to_float ( uint16_t half )

extern

Converts a float16 bit pattern to a 32-bit float.

Parameters

half	16-bit float16 bit pattern to convert.

Returns

32-bit float value.

Algorithm:

1. Extract sign, exponent, mantissa from half-precision fields
2. Handle zero, subnormal (normalize), infinity/NaN, and normal cases
3. Rebias exponent and expand mantissa to single-precision format

* @param half 16-bit float16 bit pattern
* 

Returns

32-bit float

OpenLcbFloat16_negate()

uint16_t OpenLcbFloat16_negate ( uint16_t half )

extern

Flips the sign/direction bit of a float16 value and returns the result.

Parameters

half	16-bit float16 bit pattern to negate.

Returns

float16 bit pattern with the sign bit flipped.

Flips the sign/direction bit of a float16 value and returns the result.

OpenLcbFloat16_is_nan()

bool OpenLcbFloat16_is_nan ( uint16_t half )

extern

Returns true if the float16 bit pattern represents NaN (speed not available).

Parameters

half	16-bit float16 bit pattern to test.

Returns

true if the value is NaN, false otherwise.

Returns true if the float16 bit pattern represents NaN (speed not available).

OpenLcbFloat16_is_zero()

bool OpenLcbFloat16_is_zero ( uint16_t half )

extern

Returns true if the float16 bit pattern represents positive or negative zero.

Parameters

half	16-bit float16 bit pattern to test.

Returns

true if the value is zero, false otherwise.

OpenLcbFloat16_speed_with_direction()

uint16_t OpenLcbFloat16_speed_with_direction ( float speed, bool reverse )

extern

Encodes a speed magnitude and direction into a float16 bit pattern.

Parameters

speed	Speed magnitude as a 32-bit float.
reverse	true for reverse direction, false for forward.

Returns

float16 bit pattern encoding the speed and direction.

OpenLcbFloat16_get_speed()

float OpenLcbFloat16_get_speed ( uint16_t half )

extern

Returns the speed magnitude from a float16 bit pattern (ignores direction).

Parameters

half	16-bit float16 bit pattern to decode.

Returns

Speed magnitude as a 32-bit float.

OpenLcbFloat16_get_direction()

bool OpenLcbFloat16_get_direction ( uint16_t half )

extern

Returns true if the direction bit is set (reverse).

Parameters

half	16-bit float16 bit pattern to test.

Returns

true if the direction bit is set (reverse), false otherwise.