Marvelmind API

This chapter as a clean, readable HTML page.

The “Marvelmind API” chapter of the Interfaces and Protocols, reproduced as a real HTML page. Anything unclear? Open the original PDF of just this chapter (pages 127-213) (also pinned top-left). Hub: all chapters.

Check connection to API

After running example software, press “space” button in terminal, type command ‘version’ and press enter. If the example software prints version of API, it can communicate with API library.

mm_api_version

Marvelmind API library description

API is coming as dynamic-link library (DLL) for MS Windows and shared library for Linux (x86 and ARM platforms). The library includes set of functions for monitoring and controlling Marvelmind system via modem connected to USB port of the computer. This section of document contains description of all these functions.

To provide more compatibility with different programming languages, most of complex data structures are passing via untyped pointers to memory. Functions description include offset of every data field in the memory pool. In the file ‘marvelmind_api.c’ from the example software you can see implementation of moving data between memory pools and fields in C structures.

Types of parameters in the description are shown in C syntax. Here is description of the types:

Type	Size (bytes)	Description
bool	1	Boolean type. Zero means false, non-zero means true
uint8_t	1	Unsigned integer value, 0…255
int8_t	1	Signed integer value in two’s complement format, -128…127
uint16_t	2	Unsigned integer value, 0…65535
int16_t	2	Signed integer value in two’s complement format, -32768…32767
uint32_t	4	Unsigned integer value, 0…4294967295
int32_t	4	Signed integer value in two’s complement format, -2147483648…2147483647
void *	4/8	Memory pointer (address in memory). 4 bytes for 32-bit platforms, 8 bytes for 64-bit platforms.

Each function description includes set of API versions where this function is available. New API versions will support more functions for new features in Marvelmind system. Now not all features available in Dashboard are available via API, so if you need more API functions please ask at info@marvelmind.com.

List of supported functions:

Function	API versions	License needed
Get version of Marvelmind API library	V1+	none
Get last error	V6+	none
Try to open serial port	V1+	none
Try to open serial port by given name	V2+	none
Try to open UDP port	V9+	none
Close serial port	V1+	none
Get version and CPU ID of Marvelmind device	V1+	none
Get list of devices	V1+	none
Wake device	V1+	none
Send device to sleep	V1+	none
Get telemetry data from beacon	V1+	none
Get latest location data	V1+	none
Get latest location data (with angle)	V3+	none
Set location of the beacon	V3+	MMSW0005
Set distance between beacons	V4+	MMSW0005
Get latest raw distances data	V1+	none
Get height of the hedgehog	V4+	none
Set height of the hedgehog	V4+	MMSW0005
Get height of stationary beacon in submap	V4+	none
Set height of stationary beacon in submap	V4+	MMSW0005
Get location update rate setting	V1+	none
Set location update rate setting	V1+	MMSW0005
Add submap	V1+	MMSW0005
Delete submap	V1+	MMSW0005
Freeze submap	V1+	MMSW0005
Unfreeze submap	V1+	MMSW0005
Get submap settings	V1+	none
Set submap settings	V1+	MMSW0005
Freese map	V4+	MMSW0005
Unfreeze map	V4+	MMSW0005
Get ultrasonic settings of the beacon	V1+	none
Set ultrasonic settings of the beacon	V1+	MMSW0005
Erase map	V1+	MMSW0005
Reset device to default settings	V1+	MMSW0005
Connect beacons to axes	V2+	MMSW0005
Read modem’s configuration memory dump	V3+	MMSW0005
Write modem’s configuration memory dump	V3+	MMSW0005
Get temperature of air setting from modem	V3+	none
Set temperature of air setting in modem	V3+	none
Software reset of the device	V3+	none
Get beacon real-time player settings	V6+	none
Set beacon real-time player settings	V6+	MMSW0005
Get georeferencing settings	V6+	none
Set georeferencing settings	V6+	MMSW0005
Get mode of updating positions	V6+	none
Set mode of updating positions	V6+	MMSW0005
Command to update positions	V6+	MMSW0005
Set geofencing alarm state for the beacon	V9+	MMSW0005 MMSW0006
Send generic user payload data	V9+	MMSW0005
Get generic user payload data	V9+	MMSW0005
Send command for manual distances measurement	V9+	MMSW0011
Get streaming data from modem	V9+	none
Check if the device type is modem	V1+	none
Check if the device type is stationary beacon	V1+	none
Check if the device type is hedgehog	V1+	none

Get version of Marvelmind API library

Reads version of the API library. Required to ensure the needed functions are available in this version of library.

Function name: mm_api_version

Declaration in C: bool mm_api_version(void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer.

Type	Description
uint32_t	Version of API library

Get last error

Reads status of last operation with API library to differ causes of the error.

Function name: mm_get_last_error

Declaration in C: bool mm_get_last_error(void *pdata);

Available for API versions: V6+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer.

Type

Description

uint32_t

Status of last operation:

0: operation successfully executed

1: communication error

2: error opening serial port

3: license is required

Open serial port

Opens port where Marvelmind device (modem or beacon) is connected via USB (virtual serial port). You don’t need to specify serial port name, because the API searching all serial ports and checks whether it corresponds to Marvelmind device or no.

Function name: mm_open_port

Declaration in C: bool mm_open_port ();

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, port is opened

false – error in execution

Parameters: none

Open serial port by given name

Opens port where Marvelmind device (modem or beacon) is connected via USB (virtual serial port). Function tries to open port with specified name.

Function name: mm_open_port_by_name

Declaration in C: bool mm_open_port_by_name(void *pdata);

Available for API versions: V2+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, port is opened

false – error in execution

Parameters:

Type	Description
void *	Pointer to serial port name – sequence of ASCII characters terminated by zero (ASCIIZ)

Open UDP port

Allows to establish communication with Super-Modem via UDP instead USB.

Function name: mm_open_port_udp

Declaration in C: bool mm_open_port_udp(void *pdata);

Available for API versions: V9+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, UDP port is opened

false – error in execution

Parameters:

Type	Description
void *	Pointer to the structure of UDP settings (see below)

Structure of data by the pointer:

Type	Description
uint16_t	UDP port to connect
uint16_t	Timeout of communication, ms
uint16_t	reserved
Up to 255 bytes	IP address- sequence of ASCII characters terminated by zero (ASCIIZ)

IP address and UDP port should correspond to the settings of the Super-Modem (see screenshot below).

Close serial port

Closes port, if it was previously opened by mm_open_port function.

Function name: mm_close_port

Declaration in C: bool mm_close_port ();

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, port is closed

false – error in execution

Parameters: none

Get version and CPU ID of Marvelmind device

Reads version and CPU ID. Version includes information about firmware version and type of device hardware. CPU ID is the unique ID of the device item.

Function name: mm_get_device_version_and_id

Declaration in C: bool mm_get_device_version_and_id (uint8_t address, void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, version and CPU ID data retrieved

false – error in execution

Parameters:

Type	Description
uint8_t	Address of Marvelmind device (1…254)
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint8_t	Major version of firmware (example: “6”, for version V6.07a)
uint8_t	Minor version of firmware (example: “7”, for version V6.07a)
uint8_t	Second minor version of firmware (example: “1”, for version V6.07a)
uint8_t	Device type ID (see appendix).
uint8_t	Firmware options (TBD).
uint32_t	CPU ID. Printing this value as hexadecimal gives CPU ID in form shown in dashboard and on the stickers on devices.

Get list of devices

Reads list of Marvelmind devices known to modem. The list includes list of all devices connected by radio to modem’s network, including sleeping devices.

Function name: mm_get_devices_list

Declaration in C: bool mm_get_devices_list (void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, list of devices is retrieved

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint8_t	Number of following devices in the list (N)
N*9 bytes	Sequence of N devices structures, described in next table

Structure of each device in the list:

Type	Description
uint8_t	Address of device
bool	true = duplicated address – more than 1 device with same address was found false = not duplicated address
bool	true = device is sleeping false = device not sleeping
uint8_t	Major version of firmware (example: “6”, for version V6.07a)
uint8_t	Minor version of firmware (example: “7”, for version V6.07a)
uint8_t	Second minor version of firmware (example: “1”, for version V6.07a)
uint8_t	Device type ID (see appendix).
uint8_t	Firmware options (TBD).
uint8_t	Flags: Bit 0: 1 – device connection complete – device has confirmed connection 0 – waiting for confirmation from device (like ‘Connecting…’ in dashboard). Bit 1…7 – TBD

Wake device

Sends command to wake specified device. If wake command was sent and such device is existing, the device will connect to modem in several seconds and will appear in devices list.

Function name: mm_wake_device

Declaration in C: bool mm_wake_device (uint8_t address);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, wake command was sent

false – error in execution

Parameters:

Type

Description

uint8_t

1…254 – address of Marvelmind device to wake

0 – wake all devices

Send device to sleep

Send to sleep existing device.

Function name: mm_send_to_sleep_device

Declaration in C: bool mm_send_to_sleep_device (uint8_t address);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, sleep command was sent

false – error in execution

Parameters:

Type

Description

uint8_t

1…254 – address of Marvelmind device to sleep

0 – send to sleep all devices

Get telemetry data from beacon

Reads telemetry data of Marvelmind beacon.

Function name: mm_get_beacon_telemetry

Declaration in C: bool mm_get_beacon_telemetry (uint8_t address, void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, telemetry is retrieved

false – error in execution

Parameters:

Type	Description
uint8_t	Address of Marvelmind beacon (1…254)
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint32_t	Working time of the beacon, seconds (time from reset or waking up).
int8_t	RSSI, dBm – radio signal strength
int8_t	Measured temperature, °C
uint16_t	Supply voltage, mV
16 bytes	Reserved (0)

Get latest location data

Reads latest updated coordinates pack from modem. Also reads user payload data if available.

Function name: mm_get_last_locations

Declaration in C: bool mm_get_last_locations(void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, location data was retrieved

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
18*6 bytes	6 18-byte data structures of last updated coordinates, see table below
bool	true – new raw distances are available to read
5 bytes	TBD
uint8_t	User payload data size (M)
M bytes	User payload data

Structure of each location data item:

Type	Description
uint8_t	Address of device (1…254) 0 – this data item is not filled
uint8_t	Head index (TBD)
int32_t	X coordinate, mm
int32_t	Y coordinate, mm
int32_t	Z coordinate, mm
uint8_t	Status flags (TBD)
uint8_t	Quality of positioning, 0…100%
uint8_t	TBD
uint8_t	TBD

Get latest location data (with angle)

Reads latest updated coordinates pack from modem (with angle for paired beacons). Also reads user payload data if available.

Function name: mm_get_last_locations2

Declaration in C: bool mm_get_last_locations2(void *pdata);

Available for API versions: V3+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, location data was retrieved

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
20*6 bytes	6 20-byte data structures of last updated coordinates, see table below
bool	true – new raw distances are available to read
5 bytes	TBD
uint8_t	User payload data size (M)
M bytes	User payload data

Structure of each location data item:

Type	Description
uint8_t	Address of device (1…254) 0 – this data item is not filled
uint8_t	Head index (TBD)
int32_t	X coordinate, mm
int32_t	Y coordinate, mm
int32_t	Z coordinate, mm
uint8_t	Status flags (TBD)
uint8_t	Quality of positioning, 0…100%
uint8_t	TBD
uint8_t	TBD
uint16_t	Bit 0…11 – angle of rotation in 1/10 degree (if paired beacons feature is enabled) Bit 12 – 1 = angle not available Bit 13…15 – reserved

Set location of the beacon

Manual setup of location of the specified beacon.

Function name: mm_set_beacon_location

Declaration in C: bool mm_set_beacon_location (uint8_t address, void *pdata);

Available for API versions: V3+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, location is updated

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the beacon
void *	Pointer to buffer with location data

Structure of data by pointer (should be filled before function call):

Type	Description
int32_t	New X coordinate of the beacon, mm
int32_t	New Y coordinate of the beacon, mm
int32_t	New Z coordinate of the beacon, mm

Set distance between beacons

Manual setup of distance between beacons.

Function name: mm_set_beacons_distance

Declaration in C: bool mm_set_beacons_distance (void *pdata);

Available for API versions: V4+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, distance is written

false – error in execution

Parameters:

Type	Description
void *	Pointer to buffer with distance data

Structure of data by pointer (should be filled before function call):

Type	Description
uint8_t	Address of first beacon
uint8_t	Address of second beacon
int32_t	Distance between beacons, mm

Get latest raw distances data

Reads latest updated raw distances pack from modem.

Function name: mm_get_last_distances

Declaration in C: bool mm_get_last_distances(void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, raw distances data was retrieved

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type

Description

uint8_t

Number of raw distances data items (N).

Maximum number of raw distances per request is 16: N<=16

9*N bytes

N 9-byte data structures of last raw distances, see table below

Structure of each raw distance data item:

Type	Description
uint8_t	Address of ultrasonic RX device (1…254) 0 – this data item is not filled
uint8_t	RX Head index (TBD)
uint8_t	Address of ultrasonic TX device (1…254) 0 – this data item is not filled
uint8_t	TX Head index (TBD)
uint32_t	Distance from TX device to RX device, mm
uint8_t	TBD

Get height of the hedgehog

Returns height of mobile beacon (hedgehog).

Function name: mm_get_hedge_height

Declaration in C: bool mm_get_hedge_height (uint8_t address, void *pdata);

Available for API versions: V4+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, height is returned

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the hedgehog
void *	Pointer to buffer with height data

Structure of data by pointer:

Type	Description
int32_t	Height of the hedgehog, mm

Set height of the hedgehog

Setup height of mobile beacon (hedgehog).

Function name: mm_set_hedge_height

Declaration in C: bool mm_set_hedge_height (uint8_t address, void *pdata);

Available for API versions: V4+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, height is changed

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the hedgehog
void *	Pointer to buffer with height data

Structure of data by pointer (should be filled before function call):

Type	Description
int32_t	Height of the hedgehog, mm

Get height of the stationary beacon in submap

Returns height of stationary beacon in submap.

Function name: mm_get_beacon_height

Declaration in C: bool mm_get_beacon_height (uint8_t address, void *pdata);

Available for API versions: V4+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, height is returned

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the beacon
void *	Pointer to buffer with height data

Structure of data by pointer:

Type	Description
uint8_t	Submap ID, should be filled before function call
int32_t	Height of the beacon, mm

Set height of the stationary beacon in submap

Setup height of stationary beacon in submap.

Function name: mm_set_beacon_height

Declaration in C: bool mm_set_beacon_height (uint8_t address, void *pdata);

Available for API versions: V4+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, height is changed

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the beacon
void *	Pointer to buffer with height data

Structure of data by pointer (should be filled before function call):

Type	Description
uint8_t	Submap ID
int32_t	Height of the beacon, mm

Get location update rate setting

Reads location update rate setting from modem.

Function name: mm_get_update_rate_setting

Declaration in C: bool mm_get_update_rate_setting (void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, update rate was retrieved

false – error in execution

Parameters:

Type	Description
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint32_t	Location update rate setting in mHz. So, 1000 is returned for 1 Hz, 16000 for 16 Hz, 50 for 0.05 Hz mode.

Set location update rate setting

Writes location update rate setting to modem.

Function name: mm_set_update_rate_setting

Declaration in C: bool mm_set_update_rate_setting (void *pdata);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, update rate was changed

false – error in execution

Parameters:

Type	Description
void *	Pointer to data

Structure of data by pointer (should be filled before function call):

Type	Description
uint32_t	Location update rate setting in mHz. So, 1000 is returned for 1 Hz, 16000 for 16 Hz, 50 for 0.05 Hz mode. The system will use most close to specified update rate from the series: 0.05 Hz, 0.1 Hz, 0.2 Hz, 0.5 Hz, 1 Hz, 2 Hz, 4 Hz, 8 Hz, 12 Hz, 16 Hz, 16+Hz.

Add submap

Adds new submap.

Function name: mm_add_submap

Declaration in C: bool mm_add_submap (uint8_t submapId);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, submap was added

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID to add (0…254)

Delete submap

Delete existing submap.

Function name: mm_delete_submap

Declaration in C: bool mm_delete_submap (uint8_t submapId);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, submap was removed

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID to delete (0…254)

Freeze submap

Freezes submap.

Function name: mm_freeze_submap

Declaration in C: bool mm_freeze_submap (uint8_t submapId);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, submap is frozen

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID to freeze (0…254)

Unfreeze submap

Unfreezes submap.

Function name: mm_unfreeze_submap

Declaration in C: bool mm_unfreeze_submap (uint8_t submapId);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, submap is unfrozen

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID to unfreeze (0…254)

Get submap settings

Reads submap settings from modem.

Function name: mm_get_submap_settings

Declaration in C: bool mm_get_submap_settings (uint8_t submapId, void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, submap settings were retrieved

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID (0…254)
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint8_t	Starting beacon trilateration
uint8_t	Starting set of beacons, beacon 1
uint8_t	Starting set of beacons, beacon 2
uint8_t	Starting set of beacons, beacon 3
uint8_t	Starting set of beacons, beacon 4
bool	true = 3D navigation enabled
bool	true = Submap is used only for Z coordinate
bool	true = manual limitation distance false = auto limitation distance
uint8_t	Maximum distance, meters (for manual limitation distances)
int16_t	Submap X shift, cm
int16_t	Submap Y shift, cm
int16_t	Submap Z shift, cm
uint16_t	Submap rotation, centidegrees
int16_t	Plane rotation quaternion, W (quaternion is normalized to 10000)
int16_t	Plane rotation quaternion, X
int16_t	Plane rotation quaternion, Y
int16_t	Plane rotation quaternion, Z
int16_t	Service zone thickness, cm
int16_t	Hedges height in 2D mode
bool	true = submap is frozen
bool	true = submap is locked
bool	true = stationary beacons are higher than mobile
bool	true = submap is mirrored
4 bytes	List of addresses of beacons in submap (0 = none)
8 bytes	List of ID’s of nearby submaps (255 = none)
uint8_t	Number of service zone polygon points (P)
P*4 bytes	List of service zone polygon points structures (see below)

Structure of service zone polygon point:

Type	Description
int16_t	X, cm
int16_t	Y, cm

Set submap settings

Writes submap settings to modem.

Function name: mm_set_submap_settings

Declaration in C: bool mm_set_submap_settings (uint8_t submapId, void *pdata);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, submap settings were changed

false – error in execution

Parameters:

Type	Description
uint8_t	Submap ID (0…254)
void *	Pointer to data to be written (see ‘get submap settings’ function).

Freeze map

Freezes submap.

Function name: mm_freeze_map

Declaration in C: bool mm_freeze_map ();

Available for API versions: V4+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, map is frozen

false – error in execution

Unfreeze map

Freezes submap.

Function name: mm_unfreeze_map

Declaration in C: bool mm_freeze_map ();

Available for API versions: V4+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, map is unfrozen

false – error in execution

Get ultrasonic settings of the beacon

Reads ultrasonic settings from specified beacon.

Function name: mm_get_ultrasound_settings

Declaration in C: bool mm_get_ultrasound_settings (uint8_t address, void *pdata);

Available for API versions: V1+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, ultrasonic settings were retrieved

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the beacon (1…254)
void *	Pointer to data to be filled

Structure of data returned via pointer:

Type	Description
uint16_t	Frequency of ultrasound TX (not relevant for DSP RX-only beacons)
uint8_t	Number of TX periods (not relevant for DSP RX-only beacons)
bool	true= use AGC for RX false = manual gain for RX
uint16_t	Manual gain value (0…4000)
bool	true = Sensor RX1 is enabled in normal mode
bool	true = Sensor RX2 is enabled in normal mode
bool	true = Sensor RX3 is enabled in normal mode
bool	true = Sensor RX4 is enabled in normal mode
bool	true = Sensor RX5 is enabled in normal mode
bool	true = Sensor RX1 is enabled in frozen mode
bool	true = Sensor RX2 is enabled in frozen mode
bool	true = Sensor RX3 is enabled in frozen mode
bool	true = Sensor RX4 is enabled in frozen mode
bool	true = Sensor RX5 is enabled in frozen mode
uint8_t	Index of DSP RX filter (relevant only for DSP beacons) 0 = 19 kHz 1 = 25 kHz 2 = 31 kHz 3 = 37 kHz 4 = 45 kHz

Set ultrasonic settings of the beacon

Write ultrasonic settings to specified beacon.

Function name: mm_set_ultrasound_settings

Declaration in C: bool mm_set_ultrasound_settings (uint8_t address, void *pdata);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, ultrasonic settings were changed

false – error in execution

Parameters:

Type	Description
uint8_t	Address of the beacon (1…254)
void *	Pointer to data to be written (see ‘get ultrasonic settings’ function).

Erase map

Erase map in modem – remove all submaps (except submap 0), reset submap 0 to initial state, remove all connected beacons from network.

Function name: mm_erase_map

Declaration in C: bool mm_erase_map ();

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, map erased

false – error in execution

Parameters: none

Reset device to default settings

Reset device to default settings (radio, ultrasonic etc).

Function name: mm_set_default_settings

Declaration in C: bool mm_set_default_settings (uint8_t address);

Available for API versions: V1+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, device was reset to default settings

false – error in execution

Parameters:

Type

Description

uint8_t

Address of the device (1…254)

255 – reset to default the device connected via USB

Connect beacons to axes

Shift map so selected beacons will be on axes.

Function name: mm_beacons_to_axes

Declaration in C: bool mm_beacons_to_axes (uint8_t address_0, uint8_t address_x, uint8_t address_y);

Available for API versions: V2+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, map shifted

false – error in execution

Parameters:

Type	Description
uint8_t	address_0 – address of beacon which should be in the center (X=0, Y=0)
uint8_t	address_x – address of beacon which should be along X axis (Y= 0)
uint8_t	address_y – address of beacon which should be in positive direction of Y (Y>0)

Read dump of modem’s configuration memory

Reads dump of modem’s configuration memory. Allows saving modem’s settings and stored map.

Function name: mm_read_flash_dump

Declaration in C: bool mm_read_flash_dump(uint32_t offset, uint32_t size, void *pdata);

Available for API versions: V3+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, dump was read

false – error in execution

Parameters:

Type	Description
uint32_t	offset – offset from start of configuration memory, bytes
uint32_t	size – size of data to read, bytes
void *	pdata – pointer to user’s buffer for receiving data

Write dump of modem’s configuration memory

Write data dump to modem’s configuration memory. Allows to restore modem’s settings and map.

Function name: mm_write_flash_dump

Declaration in C: bool mm_write_flash_dump(uint32_t offset, uint32_t size, void *pdata);

Available for API versions: V3+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed, dump was written

false – error in execution

Parameters:

Type	Description
uint32_t	offset – offset from start of configuration memory, bytes For correct operation offset should be aligned to 4096 bytes page (value 0, 4096, 8192 and so on).
uint32_t	size – size of data to write, bytes
void *	pdata – pointer to user’s buffer with data

Note: After writing the configuration, software reset of the modem (mm_reset_device(255)) is recommended to apply new settings and prevent overwriting them.

Restart (soft reset) of the device

Executes software reset for specified device.

Function name: mm_reset_device

Declaration in C: bool mm_reset_device (uint8_t address);

Available for API versions: V3+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, device is resetting

false – error in execution

Parameters:

Type

Description

uint8_t

Address of the device (1…254)

255 -software reset for device connected via USB

Read temperature of air setting from modem

Reads temperature of air setting (in Celsius degrees) from modem.

Function name: mm_get_air_temperature

Declaration in C: bool mm_get_air_temperature (void *pdata);

Available for API versions: V3+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, temperature is returned

false – error in execution

Structure of data returned via pdata pointer:

Type	Description
int8_t	Temperature of air, Celsius degrees

Write temperature of air setting to modem

Setup temperature of air setting (in Celsius degrees) in modem.

Function name: mm_set_air_temperature

Declaration in C: bool mm_set_air_temperature (void *pdata);

Available for API versions: V3+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed, temperature was written

false – error in execution

Structure of data which user should supply via pdata pointer:

Type	Description
int8_t	Temperature of air, Celsius degrees

Get beacon real-time player settings

Reads real-time player settings for the beacon.

Function name: mm_get_realtime_player_settings

Declaration in C: bool mm_get_realtime_player_settings (uint8_t address, void *pdata);

Available for API versions: V6+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
uint8_t	address – address of the beacon (1…254)
void *	pdata – pointer to data to be filled

Structure of data returned via pointer:

Type	Description
bool	true = real-time player is enabled
uint8_t	Number of real-time player forward samples to process
uint8_t	Number of real-time player backward samples to process
uint8_t	Reserved (0)
uint8_t	Reserved (0)

Set beacon real-time player settings

Setup real-time player settings for the beacon.

Function name: mm_set_realtime_player_settings

Declaration in C: bool mm_set_realtime_player_settings (uint8_t address, void *pdata);

Available for API versions: V6+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
uint8_t	address – address of the beacon (1…254)
void *	pdata – pointer to data to write (see ‘Get beacon real-time player settings’ function)

Get georeferencing settings

Reads georeferencing settings (geo location of point (X=0,Y=0) of Marvelmind map).

Function name: mm_get_georeferencing_settings

Declaration in C: bool mm_get_georeferencing_settings (void *pdata);

Available for API versions: V6+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to be filled

Structure of data returned via pointer:

Type	Description
int32_t	Latitude, x10^-7 degrees
int32_t	Longitude, x10^-7 degrees

Set georeferencing settings

Setup georeferencing settings (geo location of point (X=0,Y=0) of Marvelmind map).

Function name: mm_set_georeferencing_settings

Declaration in C: bool mm_set_georeferencing_settings (void *pdata);

Available for API versions: V6+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to write (see ‘Get georeferencing settings’ function)

Get mode of updating positions

Reads current mode of updating positions of mobile beacons.

Function name: mm_get_update_position_mode

Declaration in C: bool mm_get_update_position_mode (void *pdata);

Available for API versions: V6+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to be filled

Structure of data returned via pointer:

Type

Description

uint8_t

Mode of updating positions of mobile beacons:

0 – auto update positions (default mode)

1 – update positions by user request at next update cycle

2 – update positions by user request immediately

7 bytes

Reserved (0)

Set mode of updating positions

Setup mode of updating positions of mobile beacons.

Function name: mm_set_update_position_mode

Declaration in C: bool mm_set_update_position_mode (void *pdata);

Available for API versions: V6+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to write (see function ‘Get mode of updating positions’)

Command to update positions

Send command to update positions of mobile beacons (if update mode is not automatic).

Function name: mm_set_update_position_command

Declaration in C: bool mm_set_update_position_command (void *pdata);

Available for API versions: V6+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to write

Structure of data by pointer:

Type	Description
8 bytes	Reserved (0)

Set geofencing alarm state for the beacon

Send command to setup alarm state on the beacon’s alarm pin (for Super-Beacon).

Alarm state of the pin can be specified via ‘Alarm pin mode’ setting in the ‘Interfaces’ section of settings in the dashboard (if MMSW0006 license is activated).

Function name: mm_set_alarm_state

Declaration in C: bool mm_set_alarm_state (uint8_t address, void *pdata);

Available for API versions: V9+

License required: MMSW0005, MMSW0006

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
uint8_t	address – address of the beacon (1…254)
void *	pdata – pointer to data to write

Structure of data by pointer:

Type	Description
uint8_t	Alarm pin mode: 0 – pin is automatically controlled according to geofencing status 1 – pin is manually controlled – no alarm state 2 – pin is manually controlled – alarm state
uint8_t	Geofencing zone index – number of geofencing zone which beacon will stream out in the alarm state
6 bytes	Reserved (0)

Send generic user payload data

Sends generic user payload data. If the API is connected to the modem, data will be transmitted via UART/USB port of the specified mobile beacon. If the API is connected to the mobile beacon, data will be transmitted via UART/USB port of the modem. Received data are available on the remote side by receiving API function, Arduino examples, ROS and other software.

Function name: mm_send_user_payload_data

Declaration in C: bool mm_send_user_payload_data (uint8_t address, void *pdata);

Available for API versions: V9+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type

Description

uint8_t

address – address of the beacon (1…254) if the API is connected to modem

n/a if the API is connected to the beacon

void *

pdata – pointer to data to write

Structure of data by pointer:

Type	Description
uint8_t	Size of data to transmit
256 bytes	Generic data buffer to transmit

Get generic user payload data

Receives generic user payload data, sent by transmitting API function, Arduino, ROS or other user software. If the API is connected to the modem, this function can receive data transmitted via UART/USB port of the mobile beacon. If the API is connected to the mobile beacon, this function can receive data transmitted via the modem.

Function name: mm_get_user_payload_data

Declaration in C: bool mm_get_user_payload_data (void *pdata);

Available for API versions: V9+

License required: MMSW0005

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to receive

Structure of received data by pointer:

Type	Description
uint8_t	address – address of the beacon
int64_t	Timestamp of data transmission – number of milliseconds from 01.01.1970 (Unix time)
uint8_t	Size of data to transmit
256 bytes	Buffer of received data

Send command for manual distances measurement

Sends command for measurement distances from specified beacon to other beacons in the system. In current version of software supported in IA (Inverse architecture).

Function name: mm_send_distances_measurement_command

Declaration in C: bool mm_send_distances_measurement_command (void *pdata);

Available for API versions: V9+

License required: MMSW0011

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to send

Structure of data by pointer:

Type	Description
uint8_t	Mode: 0 – auto 1 – manual (by this command)
uint8_t	Address of the beacon
uint32_t	Maximum distance to measure, mm
8 bytes	Reserved

Get streaming data from modem

Reads modem’s streaming data in the previously described format.

Function name: mm_get_stream_data

Declaration in C: bool mm_get_stream_data (void *pdata);

Available for API versions: V9+

License required: none

Returned value:

Type

Description

bool

true – function successfully executed

false – error in execution

Parameters:

Type	Description
void *	pdata – pointer to data to send

Structure of data by pointer:

Type	Description
uint8_t	Number of stream records in this reply (0…16)
138*16 bytes	16 streaming records by 138 bytes (see below)
8 bytes	Reserved

Structure of stream record:

Type	Description
uint8_t	Record size, bytes
uint8_t	Record type. Same value as ‘line type’ in the dashboard log file. For example, 41 means Marvelmind protocol data
8 bytes	Reserved
128 bytes	Stream record data

Check whether device type is modem

Checks whether the specified device type corresponds to modem.

Function name: mm_device_is_modem

Declaration in C: bool mm_device_is_modem (uint8_t deviceType);

Available for API versions: V1+

License required: none

Returned value:

Type	Description
bool	true – specified device type corresponds to modem

Parameters:

Type	Description
uint8_t	Device type to check

Check whether device type is stationary beacon

Checks whether the specified device type corresponds to stationary beacon.

Function name: mm_device_is_beacon

Declaration in C: bool mm_device_is_beacon (uint8_t deviceType);

Available for API versions: V1+

License required: none

Returned value:

Type	Description
bool	true – specified device type corresponds to stationary beacon

Parameters:

Type	Description
uint8_t	Device type to check

Check whether device type is hedgehog

Checks whether the specified device type corresponds to hedgehog.

Function name: mm_device_is_hedgehog

Declaration in C: bool mm_device_is_hedgehog (uint8_t deviceType);

Available for API versions: V1+

License required: none

Returned value:

Type	Description
bool	true – specified device type corresponds to hedgehog

Parameters:

Type	Description
uint8_t	Device type to check

Description of C example for Marvelmind API

C example is used for testing of Marvelmind API and can be used as basis for building of user application.

The C example is the console application. It was tested on following platforms:

CPU: Intel Core 2 Duo, OS: MS Windows XP;
CPU: Intel Core i5, OS: Linux Ubuntu 16.04;
Raspberry Pi 3 Model B+, OS: Raspbian (2018-11-13-raspbian-stretch-full)

On the Windows platform the example was built with CodeBlocks IDE and so the example includes CodeBlocks project file.

On the Linux platforms, the example was built with using make utility and so the example includes makefile for this.

The example includes following modules:

File name	Description
main.c	Module with main () function. Calls of functions of example and implements simple command line interface.
marvelmind_example.c marvelmind_example.h	marvelmindStart() – initialization of the example marvelmindFinish() – called after finishing work with API marvelmindCycle() – frequently called from main loop Also, module includes several function for processing commands entered by user.
marvelmind_api.c marvelmind_api.h	marvelmindAPILoad() – loads API library marvelmindAPIFree() – frees memory used by API library All functions of communication with API library.
marvelmind_devices.c marvelmind_devices.h	Supports list of beacons retrieved from modem by calling ‘get devices list’ command. Each beacon includes data about its location and distances to other beacons.
marvelmind_pos.c marvelmind_pos.h	Reads latest location data and latest raw distances. Updates these data in the devices list.
marvelmind_utils.c marvelmind_utils.h	Some helper functions used by other modules.

How the example works:

Try to open serial port until success
When port is opened, the program reads version of device connected via USB. If this is modem, the program continues to execute next steps
When connected to modem, the program reads the devices list with 1 Hz rate. The devices list is compared with currently stored in marvelmind_devices.c module and the list in marvelmind_devices.c is updated, if any changes are detected. All changes are printed in console
When connected to modem, the program reads the latest location data with 20 Hz rate. If the flag of new raw distances data is set, the program reads latest raw distances. The program compares locations and distances with data in devices list in marvelmind_devices.c and updates the data if they are changed. All changed data are printed in console
If the program can’t get latest location data for 10 times, it closes the port and returns to step 1 – tries to open the port again. Reopening of the port is needed for cases when modem was disconnected and connected back to USB
If user press ‘space’ button, the program shows ‘Enter command: ‘ message and waits for user command. Most of API functions are called by user command, see below for details

User commands:

If user press ‘space’ button when program is running, the program shows message ‘Enter command: ‘. User should type command on keyboard and press enter.

The table below contains format of all user commands:

Commands group

Description

API version

Format of command:

version

Action:

Prints version of API library

Exit from program

Format of command:

quit

Action:

Finishes program execution

Sleep/wake

Format of command:

wake <address>

Action:

Execute wake command.

Examples:

wake 5 – send command to wake device 5

wake 0 – send command to wake all devices

Format of command:

sleep <address>

Action:

Execute sending to sleep command.

Examples:

sleep 5 – send to sleep device 5

sleep 0 – send to sleep all devices

Default

Format of command:

default <address>

Action:

Execute reset to default settings command.

Examples:

default 5 – set default settings for device 5

Read telemetry

Format of command:

tele <address>

Action:

Reads and prints telemetry data of beacon.

Examples:

tele 5 – read and print telemetry of beacon 5

Submap commands

Format of command:

submap add <submapId>

Action:

Execute command to add submap with specified submap ID.

Example:

submap add 1 – add submap 1

Format of command:

submap delete <submapId>

Action:

Execute command to delete submap with specified submap ID.

Example:

submap delete 1 – delete submap 1

Format of command:

submap freeze <submapId>

Action:

Execute command to freeze submap with specified submap ID.

Example:

submap freeze 0 – freeze submap 0

Format of command:

submap unfreeze <submapId>

Action:

Execute command to unfreeze submap with specified submap ID.

Example:

submap unfreeze 0 – unfreeze submap 0

Format of command:

submap get <submapId>

Action:

Execute command to get settings of submap with specified submap ID.

Example:

submap get 0 – get and print settings of submap 0

Format of command:

submap testset <submapId>

Action:

Execute command to set settings of submap with specified submap ID. The program writes some predefined settings for testing of the command; please see the example code.

Example:

submap testset 0 – modify settings of submap 0

Map commands

Format of command:

map erase

Action:

Execute erase map command.

Example:

map erase – erase map in modem

Format of command:

map freeze

Action:

Execute freeze map command.

Example:

map freeze – freeze map

Format of command:

map unfreeze

Action:

Execute unfreeze map command.

Example:

map unfreeze – unfreeze map

Update rate commands

Format of command:

rate get

Action:

Execute reading update rate setting command.

Example:

rate get – read and print update rate setting

Format of command:

rate set <value>

Action:

Execute change update rate setting command. Value is given in Hz

Example:

rate set 0.5 – set update rate 0.5 Hz

Ultrasound commands

Format of command:

usound get <address>

Action:

Execute reading ultrasonic settings for specified beacon.

Example:

usound get 5 – read and print ultrasound settings of beacon 5

Format of command:

usound testset <address>

Action:

Execute writing ultrasonic settings for specified beacon. The program writes some predefined settings for testing of the command; please see the example code.

Example:

usound testset 5 – modify ultrasound settings of beacon 5

Connect to axes command

Format of command:

axes <address_0> <address_x> <address_y>

Action:

Execute connect beacons to axes command..

Example:

axes 3 4 5 – set beacon 3 to X=0, Y=0; beacon 4 along X (Y=0) and beacon 5 above X (Y>0)

Read configuration memory dump from modem

Format of command:

read_dump <offset> <size>

Action:

Execute read dump of modem configuration memory command.

Example:

read_dump 0 1000 – read first 1000 bytes from beginning of configuration memory

Write configuration memory test dump to modem

Format of command:

write_dump_test <offset> <size>

Action:

Execute write dump of modem configuration memory command.

Example:

write_dump_test 0 1000 – fills first 1000 bytes from beginning of configuration memory by test pattern

Software reset of device

Format of command:

reset <address>

Action:

Execute software reset command.

Example:

reset 255 – executes software reset for device connected via USB

Temperature of air commands

Format of command:

temperature get

Action:

Execute reading temperature of air setting from modem

Example:

temperature get read and print ultrasound temperature of air setting

Format of command:

temperature set <value>

Action:

Execute writing temperature of air setting to modem

Example:

temperature set 30 setup temperature of air setting to 30 Celsius degrees

Set location of beacon

Format of command:

setloc <address> <X > <Y > <Z>

Action:

Execute set location of the beacon command. X, Y, Z are coordinates in meters.

Example:

setloc 12 1.51 3.45 2.0 – sets location of beacon 12 to X= 1.51 m, Y= 3.45 m, Z= 2.0 m

Set distance between beacons

Format of command:

setdist <address1> <address2 > <distance>

Action:

Execute set distance between beacons command. Address1 and address2 are addresses of beacons. Distance is distance in meters.

Example:

setdist 12 13 16.5 – sets distance between beacons 12 and 13 to 16.5 meters

Heights commands

Format of command:

height_h get <address>

Action:

Execute get hedge height command. Address is the address of the hedgehog.

Example:

height_h get 15 – reads and prints height of hedgehog 15

Format of command:

height_h set <address> <height>

Action:

Execute set hedge height command. Address is the address of the hedgehog. Height in meters

Example:

height_h set 15 2.5 – setup height of hedgehog 15 to 2.5 meters

Format of command:

height_b get <address> <submap_id>

Action:

Execute get stationary beacon height command. Address is the address of the beacon. Submap_id is ID of submap where beacon belongs.

Example:

height_b get 12 0 – reads and prints height of stationary beacon 12 in submap 0.

Format of command:

height_b set <address> <submap_id> <height>

Action:

Execute set stationary beacon height command. Address is the address of the hedgehog. Submap_id is ID of submap where beacon belongs. Height in meters

Example:

height_b set 12 0 5.1 – setup height of beacon 12 in submap 0 to 5.1 meters

Real-time player commands

Format of command:

rtp get <address>

Action:

Execute get real-time player settings command. Address is the address of the beacon.

Example:

rtp get 15 – reads and prints real-time player settings of beacon 15

Format of command:

rtp testset <address>

Action:

Execute set real-time player settings command. Address is the address of the beacon. The program writes some predefined settings for testing of the command; please see the example code.

Example:

rtp testset 15 – setup test real-time player settings for beacon 15

Georeferencing commands

Format of command:

georef get

Action:

Execute get georeferencing settings command.

Example:

georef get – reads and prints georeferencing settings

Format of command:

georef set <latitude> <longitude>

Action:

Execute set georeferencing settings command.

Example:

georef set 10 20 – write georeferencing 10 degrees latitude, 20 degrees longitude

Update mode commands

Format of command:

update_mode get

Action:

Execute get positions update mode command.

Example:

update_mode get – reads and prints positions update mode

Format of command:

update_mode set <mode>

Action:

Execute set positions update mode command.

Example:

update_mode set 0 – set automatic mode of positions update

Format of command:

update

Action:

Execute update positions command.

Example:

update – update positions of mobile beacons according to current mode

Set geofencing alarm state

Format of command:

alarm <address> <mode> <zone>

Action:

Execute set geofencing alarm state command.

Example:

alarm 10 2 5 – set geofencing alarm signal on the beacon n10 with geofencing zone number 5

User payload commands

Format of command:

payload read <address>

Action:

Execute get user payload data command.

Example:

payload read – read user payload from any beacon/modem

Example:

payload read 10 – read user payload from beacon n10

Format of command:

payload write <address>

Action:

Execute send user payload data command.

Example:

payload write 10 – write test payload data to beacon n10

Test pattern is 40 bytes started from 100: 100,101,…, 139

Manual distance measurement command

Format of command:

distance <manual/auto> <address> <max distance>

Action:

Execute manual distance measurement command.

Example:

distance manual 10 5 – measure distances from beacon 10 to others, maximum distance 5 meters

Example:

distance manual 10 – measure distances from beacon 10 to others, maximum distance 30 meters (default)

Example:

distance auto – return to automatic distances measurement mode

Device types

Here is the list of ‘Device type ID’ values for specific devices:

Device type ID	Device description
22	Beacon HW V4.5
23	Beacon HW V4.5 (hedgehog mode)
24	Modem HW V4.9
30	Beacon HW V4.9
31	Beacon HW V4.9 (hedgehog mode)
32	Beacon Mini-RX
36	Beacon Mini-TX
37	Beacon-TX-IP67
41	Beacon industrial-RX
42	Super-Beacon
43	Super-Beacon (hedgehog mode)
44	Industrial Super-Beacon
45	Industrial Super-Beacon (hedgehog mode)
46	Super-Modem
48	Modem HW V5.1

You can get device type id from devices list and reading device version commands.

Sending user data from/to user devices

Marvelmind supports different ways for transmission user data through Marvelmind system:

transmit data via UART or USB of the modem and receive via UART or USB from the mobile beacon
transmit data via UART or USB of the mobile beacon and receive via UART or USB of the modem.

Super-Modem also supports transmission and receiving user data via UDP.

The protocols of the data transmission are described in previous sections of this document:

protocol of transmission data to user device and from user device;
API function for transmission and receiving data.

Marvelmind provides different examples of software for the communication:

Examples	Arduino (UART)	PC / Raspberry Pi (USB)				PC / raspberry Pi (UDP Super-Modem)
Examples	Arduino (UART)	API	C	Python	ROS/ROS2	C example
User device ← beacon	+	+	+	+	+	n/a
Modem → User device	+	+	+	+	+	+
User device → beacon	+	+	–	–	+	n/a
Modem ← User device	+	+	–	–	+	+

The full list of the examples:

Arduino examples for sending and receiving user data are placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ arduino’. ‘hedgehog_sample_uart_user_data_receive_v2’ is for receiving user data, ‘hedgehog_sample_uart_user_data_send_v2’ is for sending user data
API communication example is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 05_API/example_source’ (source code) and ‘01_Common_Indoor_positioning_SW/ 05_API/example_bin_win32’ (binary for Windows). Data transmission or receiving can be called as described in this document.
C example for receiving of the streaming data is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ c’. Also this example is available in the repository on the GitHub. This example simply prints all data received from mobile beacon or modem, including user data.
Python example for receiving of the streaming data is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ python’. Also this example is available in the repository on the GitHub. This example simply prints all data received from mobile beacon or modem, including user data.
ROS package example for receiving of the streaming data is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ ROS. Also this package is available in the repository. The ROS package allows to receive user data and send user data through the API. See documentation for the details.
ROS-2 package example for receiving of the streaming data is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ ROS2. Also this package is available in the repository. The ROS package allows to receive user data and send user data through the API. See documentation for the details.
C example for receiving data via UDP is placed in the Marvelmind software package in folder ‘01_Common_Indoor_positioning_SW/ 06_Examples/ c’. This example simply prints all data received via UDP from Super-Modem or Dashboard, including user data. Sending user data via UDP can be done via API if API is used for connection to the Super-Modem via UDP instead USB.

Contacts

For additional support, please send your questions to info@marvelmind.com

Appendix 1. Calculating CRC-16

For checksum the CRC-16 is used. Last two bytes of N-bytes frame are filled with CRC-16, applied to first (N-2) bytes of frame. To check data, you can apply CRC-16 to all frame of N bytes, the result value should be zero.

Below is the implementation of the algorithm in the ‘C’:

typedef uint16_t ModbusCrc;

typedef union {
uint16_t w;
struct{
uint8_t lo;
uint8_t hi;
} b;
uint8_t bs[2];
} Bytes;

static ModbusCrc modbusCalcCrc(const void *buf, uint16_t length)

{

uint8_t *arr = (uint8_t *)buf;

Bytes crc;
crc.w = 0xffff;
while(length--){
char i;
bool odd;
crc.b.lo ^= *arr++;

for(i = 0; i< 8; i++){

odd = crc.w& 0x01;
crc.w>>= 1;
if (odd)
crc.w ^= 0xa001;
}
}

return (ModbusCrc) crc.w;

}

Appendix 2. Format of error reply from modem

Format of error frame (from modem to host)

Offset	Size (bytes)	Type	Description	Value
0	1	uint8_t	Address of modem	0xff
1	1	uint8_t	Type of packet
2	1	uint8_t	Code of error
3	2	uint16_t	CRC-16 (see appendix 1)

Type of the error packet is the type of packet for the request frame with added high bit. For example, if type of packet for request is 0x03, the type of error packet will be 0x83.

Code of error may be one of following:

1 – unknown type of packet in request

2 – unknown code of data in request

3 – error in data field of request

6 – device is busy

10 – error message from remote device

11 – timeout of reply from remote device