Core API

All devices supporting MDIF must implement the Core component. The Core component defines the basic functionality of a device, and it is specified in src/protobuf/mdif/core/core.proto.

Protobuf specification

The following documentation is generated from the Protobuf specification in src/protobuf/mdif/core/core.proto.

Table of Contents

mdif/common.proto

Common to all mdif protobuffers.

Status

Defines the status of a request

Name	Number	Description
SUCCESS	0	The request was successful
FAILURE	1	The request failed
ERR_INVALID	2	The request was invalid
ERR_NOT_SUPPORTED	3	The request is not supported
ERR_NOT_IMPLEMENTED	4	The request is not implemented
ERR_NOT_READY	5	The device is not ready to process the request
ERR_SIZE	6	The device cannot process the size

mdif/core/core.proto

Message allocation for the Core component are in the range:

Start	End	Radix
0x01	0x1F	Hex
1	31	Dec

CoreService

Defines the relationship between requests and responses in the Core component

Method Name	Request Type	Response Type	Description
Ping	PingReq	PingRes	Used to ping the target device
Reset	ResetReq	ResetRes	Used to reset the device
GetDeviceInfo	GetDeviceInfoReq	DeviceInfo	Used to get the device info
GetBatteryStatus	GetBatteryStatusReq	GetBatteryStatusRes	Used to get the battery status
GetIpConfig	GetIpConfigReq	GetIpConfigRes	Used to get the IP configuration
SetIpConfig	SetIpConfigReq	SetIpConfigRes	Used to set the IP configuration
GnssCompassStream	GnssCompassStreamReq	GnssCompassStreamRes	Used to enable or disable streaming of GNSS and compass data.
CompassCalibrate	CompassCalibrateReq	CompassCalibrateRes	Used to calibrate compass
CompassCalibrationStore	CompassCalibrationStoreReq	CompassCalibrationStoreRes	Used to store current compass calibration

ApiErrorInd

Api Error indication

This message is used to indicate an error in the API. E.g if a request is not properly decoded.

Field	Type	Description
error	string

CompassCalibrateReq

Start a calibration of the compass.

The device will respond with a CompassCalibrateRes message and, if the calibration was successfully started, will follow up with a CompassCalibrationCompleteInd once calibration has either succeeded, or timed out (20s-110s duration).

When the calibration is running, the device must be on a level mount or surface, and should be rotated through 360 degrees within 20s. It may be necessary to rotate the device multiple times before the calibration succeeds.

CompassCalibrateRes

Compass calibration response.

Indicates whether the calibration was started successfully.

Field	Type	Description
status	mdif.common.Status	The status of the request

CompassCalibrationAdjustedInd

Indication that opportunistic adjustment of compass calibration has happened. This happens when the device detects that is has moved a full circle within max 128 samples at the period set in GnssCompassStreamReq. The new calibration values are volatile, and will be reset on a power-cycle.

Field	Type	Description
heading_diff	float	Difference in heading for the latest measurement, due to calibration adjustment.
offset_x	int32	The updated calibration data. Internal use only. Calculated offset for X axis (Internal use only)
offset_y	int32	Calculated offset for Y axis (Internal use only)
scale_x	float	Calculated scaling for X axis (Internal use only)
scale_y	float	Calculated scaling for Y axis (Internal use only)

CompassCalibrationCompleteInd

Indication of a completed compass calibration.

On succesful completion, the new calibration values automatically replace the previous set in non-volatile memory.

Field	Type	Description
status	mdif.common.Status	The status of the calibration
offset_x	int32	Calculated offset for X axis (Internal use only)
offset_y	int32	Calculated offset for Y axis (Internal use only)
scale_x	float	Calculated scaling for X axis (Internal use only)
scale_y	float	Calculated scaling for Y axis (Internal use only)

CompassCalibrationStoreReq

Request that the current calibration values be written to non-volatile memory.

The device will respond with a CompassCalibrationStoreRes message.

CompassCalibrationStoreRes

Indicates if the calibration data has been written succesfully.

Field	Type	Description
status	mdif.common.Status

CompassHeading

Defines a compass heading

Note that the reported heading is not compensated for magnetic declination. For details on how to compensate, see resources at NOAA:

World magnetic model

Magnetic declination

Field	Type	Description
calibrated	bool	Indicates presence of calibration data. Note that moving a device to a new mount or location will require a new calibration.
heading	float	Uncompensated magnetic heading. Degrees, 0 to 360. North is 0, East is 90.
x	int32	X. Raw reading from magnetometer. For calibration purposes only.
y	int32	Y. Raw reading from magnetometer. For calibration purposes only.
z	int32	Z. Raw reading from magnetometer. For calibration purposes only.

CoreMsg

Core wire format message

This message dictates the final format on the wire for core messages. It is a oneof construct to wrap a single message at a time.

Every request (req) has a corresponding response (res). The req/res pairs are defined in the CoreService through RPC patterns.

Indications (ind) are pushed without a request at any time

Field	Type	Description
ping_req	PingReq	Request Ping response
ping_res	PingRes	Ping response
reset_req	ResetReq	Request reset of device
reset_res	ResetRes	Reset response
get_device_info_req	GetDeviceInfoReq	Request device info
get_device_info_res	DeviceInfo	Device info response
get_battery_status_req	GetBatteryStatusReq	Request battery status
get_battery_status_res	GetBatteryStatusRes	Battery status response
get_ip_config_req	GetIpConfigReq	Request IP configuration
get_ip_config_res	GetIpConfigRes	IP configuration response
set_ip_config_req	SetIpConfigReq	Set IP configuration request
set_ip_config_res	SetIpConfigRes	Set IP configuration response
gnss_compass_stream_req	GnssCompassStreamReq	Request streamed GNSS and compass updates
gnss_compass_stream_res	GnssCompassStreamRes	Response to GNSS and compass stream request.
gnss_compass_stream_ind	GnssCompassStreamInd	GNSS and compass stream data indication.
compass_calibrate_req	CompassCalibrateReq	Request a compass calibration
compass_calibrate_res	CompassCalibrateRes	Response to a compass calibration request.
compass_calibration_complete_ind	CompassCalibrationCompleteInd	Indication that a compass calibration has completed.
compass_calibration_adjusted_ind	CompassCalibrationAdjustedInd	Indication that compass calibration has been updated.
compass_calibration_store_req	CompassCalibrationStoreReq	Request to store calibration data to non-volatile memory.
compass_calibration_store_res	CompassCalibrationStoreRes	Response to a compass calibration store request.
device_announce_ind	DeviceInfo	Device Announce Indication
api_error_ind	ApiErrorInd	Api Error indication

DeviceInfo

Device info

Used in GetDeviceInfoRes and DeviceAnnounceInd

Field	Type	Description
serial_number	string	Serial number of the device
device_type	DeviceType	The type of device
device_version	uint32	The version of the device
sw_version	string	The version of the software
gnss_present	bool	Does this device have GNSS
compass_present	bool	Does this device have a compass
gnss_configurable	bool	Can GNSS settings be configured for this device.

GetBatteryStatusReq

Request battery status

The device will respond with a GetBatteryStatusRes message.

GetBatteryStatusRes

Battery status response

Field	Type	Description
status	mdif.common.Status	The status of the request
bat_low	bool	Is the battery low
bat_charging	bool	Is the battery charging
bat_volt	float	The battery voltage

GetDeviceInfoReq

Request device info

The device will respond with a GetDeviceInfoRes message.

GetIpConfigReq

Request IP configuration

The device will respond with a GetIpConfigRes message.

GetIpConfigRes

IP configuration response

Field	Type	Description
status	mdif.common.Status	The status of the request
current_ip_config	IpConfig	The current IP configuration
nvm_ip_config	IpConfig	The IP configuration set in NVM and used on boot
mac_address	bytes	The MAC address of the device
dhcp_enabled	bool	Is DHCP enabled

GnssCompassStreamInd

GNSS and compass stream data indication

Field	Type	Description
gnss_status	GnssStatus	GNSS status
compass_heading	CompassHeading	Compass heading

GnssCompassStreamReq

Request GNSS and compass data stream

The device will respond with a GnssCompassStreamRes message.

Field	Type	Description
enable	bool	Enable or disable the stream. The device will include only the elements of the stream that it supports, as indicated in GetDeviceInfoRes. A device without GNSS does not support the stream.
period	uint32	Period between GNSS updates in miliseconds. Valid range 250-1000. The compass updates are tied to the GNSS update rate. Note on Wolfpack 210: A WP210 is composite in nature - there are four zones, each addressable via MDIF as its own device. The GNSS and compass stream setup in this case is split across two zones. In the GetDeviceInfoRes message, one zone will reply compass_present=true and gnss_configurable=false. Enable the stream on this device to receive compass headings. Another zone will reply compass_present=false and gnss_configurable=true. Enable the stream on this device to change the GNSS timing.
auto_update_calibration	bool	Enable opportunistic calibration. If enabled, the calibration values will be incrementally updated when the device describes a full circle within 128 * period. Updates will be signalled with the CompassCalibrationAdjustedInd signal, and the updated values may be persisted with the CompassCalibrationStoreReq signal.

GnssCompassStreamRes

GNSS and compass stream response

Indicates whether the stream was started successfully.

Field	Type	Description
status	mdif.common.Status	The status of the request.
error_string	string	Error description string

GnssStatus

Defines a GNSS status

Field	Type	Description
pos_valid	bool	Validity of the reported position.
time_valid	SysTimeStatus	Validity of the reported system time. The time is considered valid if there is currently a valid GNSS time avaliable, or it has previously been available, and the system estimates that it has drifted less than 100us since it was lost.
pos_hacc	float	Horizontal accuracy estimate, meters.
pos_hmsl	float	Height over mean sea level, meters.
pos_vacc	float	Vertical accuracy estimate, meters.
sol_time	int64	GPS time in microseconds for this navigation solution.
p_acc	float	ECEF position accuracy estimate, meters.
ground_speed	float	Speed over ground, meters/second
heading_2d	float	2D heading. Degrees, 0 to 360. North is 0, East is 90.
sacc	float	Speed accuracy estimate, meters/s
heading_acc	float	Heading accuracy estimeate, degrees
num_sv	uint32	The number of satellites used in the current navigation solution.
fix_type	GnssFixType	The type of fix currently provided
t_acc	uint32	The estimated timing accuracy from the GNSS receiver, nanoseconds.
systime_drift	uint32	The estimated drift between the system time, and GNSS time. Microseconds.
pos_lat	double	Latitude in degrees (WGS84 ellipsoid)
pos_lon	double	Longditude in degrees (WGS84 ellipsoid)
ecef_x	double	ECEF X coordinate, meters.
ecef_y	double	ECEF Y coordinate, meters.
ecef_z	double	ECEF Z coordinate, meters.

IpConfig

Defines the IP configuration

Field	Type	Description
ip	bytes	The IP address of the device. 4 bytes. 192.168.0.13 is encoded as ip[0]=192, ip[1]=168, ip[2]=0, ip[3]=13
netmask	bytes	The netmask of the device. 4 bytes. 255.255.255.0 is encoded as netmask[0]=255, netmask[1]=255, netmask[2]=255, netmask[3]=0
gateway	bytes	The gateway of the device. 4 bytes. 192.168.0.1 is encoded as gateway[0]=192, gateway[1]=168, gateway[2]=0, gateway[3]=1

PingReq

Request Ping response

The device will respond with a PingRes message.

PingRes

Ping response

ResetReq

Request reset of device.

The device will respond with a ResetRes message, and the device will reset.

ResetRes

Reset response

Field	Type	Description
status	mdif.common.Status	The status of the reset request

SetIpConfigReq

Set IP configuration request

The device will respond with a SetIpConfigRes message. Depending on the connection used to send the request and the IP configuration set, the response may not be received.

Field	Type	Description
persist	bool	Persist the IP configuration to NVM
ip_config	IpConfig	The IP configuration to set
dhcp_enable	DhcpEnable	Enable DHCP

SetIpConfigRes

Set IP configuration response

Field	Type	Description
status	mdif.common.Status	The status of the request

DeviceType

Defines the type of device

Name	Number	Description
NOTSET	0
WINGMAN	1	Wingman man-borne RF sensor
WATCHDOG	2	Watchdog fixed RF direction finding sensor
WOLFPACK	3	Wolfpack fixed 360 degree RF direction finding sensor
PITBULL	8	Pitbull man-borne RF effector
DOBERMANN	9	Dobermann fixed RF effector
DOBERMANN_DUAL	12	Dobermann dual fixed 90 degree RF effector
DOBERMANN360	13	Dobermann 360 degree RF effector
FALCON	14	Falcon air-borne RF direction finding sensor

DhcpEnable

Defines the DHCP enable options

Name	Number	Description
DHCP_NO_CHANGE	0
DHCP_DISABLE	1
DHCP_ENABLE	2

GnssFixType

The type of GNSS fix.

Name	Number	Description
GNSS_FIX_NONE	0	No fix available.
GNSS_FIX_2D	2	2-dimensional fix.
GNSS_FIX_3D	3	3-dimensional fix.

SysTimeStatus

Defines the state of the system time.

Name	Number	Description
VALID	0	The system time is valid, and is currently being synchronized with GNSS.
VALID_DRIFTING	1	The system time was previously synchronized with GNSS, but is free-running with an estimated drift less than 100us.
NOT_VALID	2	The system time is free-running, with no synchronization.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)