Millennial Net URM-G-916 Transmitter Module User Manual Manual
Millennial Net Transmitter Module Manual
UserManual.wiki
>
Millennial Net
>
URM G 916 User Manual
Manual
Navigation menu
Upload a User Manual
Namespaces
Wiki Guide
HTML
PDF
Info
Views
User Manual
Discussion / Help
Navigation
![RK-5409-5 Reference Kit User’s Guide 4-7iBeanAPI.hiBeanAPI.hData Structures1. ibApi_APIHANDLEtypedef ibApi_INT32 ibApi_APIHANDLE;This handle represents an API session. It is created by ibApi_Open() and used by most of the other API functions. 2. ibApi_RESULTtypedef ibApi_INT32 ibApi_RESULT;The API functions are standardized to return the value ibApi_RESULT, which is a signed 32-bit integer. If the integer is negative, then it is an error code such as ibApi_RESULT_ERR_INVALIDHANDLE or ibApi_RESULT_ERR_NOTPERMITTED. (See iBeanAPI.h for a full listing of error codes.) Otherwise, the result can be ibApi_RESULT_SUCCESS or a non-negative value specific to the particular function. 3. ibApi_GROUPIDstruct ibApi_GROUPID_s { ibApi_UINT8 words[ibApi_GROUPID_SIZE];};typedef struct ibApi_GROUPID_s ibApi_GROUPID;The group ID is a 32-bit address that is used to identify a specific network of i-Bean devices and is shared by all the devices within the network. (In the current implementation, each MeshScape System group can only have one MeshGate.)The API functions are standardized to return the value ibApi_RESULT, which is a signed 32-bit integer. If the integer is negative, then it is an error code such as ibApi_RESULT_ERR_INVALIDHANDLE or ibApi_RESULT_ERR_NOTPERMITTED. (See iBeanAPI.h for a full listing of error codes.) Otherwise, the result can be ibApi_RESULT_SUCCESS or a non-negative value specific to the particular function. 4. ibApi_DEVICEIDstruct ibApi_DEVICEID_s { ibApi_UINT8 words[ibApi_DEVICEID_SIZE];};typedef struct ibApi_DEVICEID_s ibApi_DEVICEID;The device ID is a 64-bit address that uniquely identifies an i-Bean network component such as end node, mesh node, or gateway.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-83.png)
![RK-5409-5 Reference Kit User’s Guide 4-9iBeanAPI.h8. ibApi_DEVICEINFO#define ibApi_MAX_VERSION_STRLEN 32struct ibApi_DEVICEINFO_s {ibApi_UINT16 struct_size;ibApi_DEVICETYPE device_type;ibApi_CHAR hardware_version[ibApi_MAX_VERSION_STRLEN];ibApi_CHAR firmware_version[ibApi_MAX_VERSION_STRLEN];};typedef struct ibApi_DEVICEINFO_s ibApi_DEVICEINFO;This data structure is used by ibApi_GetDeviceInfo() to report static device attributes that are fixed at manufacturing time.Structure Fields:struct_size The value sizeof (ibApi_DEVICEINFO) should be assigned to this field prior to calling ibApi_GetDeviceInfo(). This allows future versions of the API to extend the struct without breaking binary compatibility.device_type The type of the device (end node, mesh node, etc.).hardware_version These two fields report the firmware and hardware version strings for firmware_version various network devices, which are useful for diagnostic purposes. An empty string may be assigned if the device does not support version reporting. 9. ibApi_DEVICESTATEenum ibApi_DEVICESTATE_e {ibApi_DEVICESTATE_OFFLINE,ibApi_DEVICESTATE_ONLINE,ibApi_DEVICESTATE_REFRESHING,};typedef ibApi_UINT16 ibApi_DEVICESTATE;These functions are used with ibApi_GetDeviceState(). When a command is issued to modify a network device, a series of network communications must occur before the change will take effect. During this time period the said to be “refreshing”, and the actual device state may be different from values visible to the API. The refresh time depends on many factors such as sampling interval, traffic level, network topology, etc.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-85.png)
![RK-5409-5 Reference Kit User’s Guide 4-13iBeanAPI.hFunctions1. ibApi_OpenibApi_FUNC ibApi_Open( ibApi_VERSION expected_version, ibApi_CONST ibApi_CHAR *server_type, ibApi_CONST ibApi_CHAR * connection_str );ibApi_Open() should be called to initialize the API before any other function is called. If the MeshScape Network Monitor software has not yet been started, this function starts the software and then connects to it. If MeshScape Network Monitor is already running, this function connects to it.The “server_type” parameter specifies the MeshScape Network Monitor executable file path. The “connection_str” parameter contains starting MeshScape Network Monitor arguments.Parameters:expected_version: (input) Should always be ibApi_EXPECTED_VERSION.server_type: (input) “[monitor path name]” path such as “..\\sagMon.exe”.connection_str: (input) "[baud rate]" baud rate: “-B115200”Return Value:An ibApi_APIHANDLE value if successful, error code (<0) if not. 2. ibApi_CloseibApi_FUNC ibApi_Close( ibApi_APIHANDLE api_hdl );This disconnects from the server and releases the API resources. This should be called before your application exits to avoid resource leaks.Parameter:api_hdl: (input) API handle returned from ibApi_Open() Return Value:An ibApi_RESULT_SUCCESS if successful, error code (<0) if not.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-89.png)
![4-14 Millennial NetUsing the MeshScape API3. ibApi_GetApiVersion()ibApi_FUNC ibApi_GetApiVersion ();This function returns the actual software version for the API, which can differ from ibApi_EXPECTED_VERSION if DLL’s are mixed.Return Value:An IbApi_VERSION value if successful, error code (<0) if not. 4. ibApi_GetNetworkList()ibApi_FUNC ibApi_GetNetworkList( ibApi_APIHANDLE api_hdl, ibApi_GROUPID networks[], ibApi_UINT32 networks_size);This retrieves a list of group ID’s for the networks managed by the server.Parameters:param api_hdl: (input) API handle returned from ibApi_Open()networks: (output) array of group ID’s that is managed by the servernetworks_size: (input) ibApi_INT32, maximum size for the network[]Return Value:The actual number of networks (which can exceed networks_size if the written data was truncated), or an error code (<0) if unsuccessful.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-90.png)
![RK-5409-5 Reference Kit User’s Guide 4-15iBeanAPI.h5. ibApi_GetDeviceList()ibApi_FUNC ibApi_GetDeviceList( ibApi_APIHANDLE api_hdl, ibApi_GROUPID network, ibApi_DEVICETYPE device_type ibApi_DEVICEID devices[], ibAPI_UINT32 devices_size );This function retrieves the ID’s of the devices in the network. The device_type parameter is a bitwise OR of the ibApi_DEVICETYPE constants that filters the result. (To retrieve all devices, use ibApi_DEVICETYPE_ANY.)Parameters:param api_hdl: (input) API handle returned from ibApi_Open().network: (input) Group ID of the network.device_type: (input) Device type filter.devices: (output) Pointer to an array of device IDs.devices_size: (input) Maximum number of device IDs that the devices array can hold.Return Value:The actual number of devices (which can exceed devices_size if the written data was truncated), or an error code (<0) if unsuccessful.6. ibApi_GetDeviceInfo()ibApi_FUNC ibApi_GetDeviceInfo( ibApi_APIHANDLE api_hdl, ibApi_DEVICEID device_id, ibApi_DEVICEINFO * device_info );This function retrieves various static device attributes that are predetermined at manufacturing time. Thus, these values only need to be queried once for a particular device. See ibApi_DEVICEINFO above for details.Note: To avoid memory corruption, the size of (ibApi_DECVICEINFO) must be allocated to the “struct_size” field prior to calling this function.Parameters:api_hdl: (input) API handle returned from ibApi_Open().device_id: (input) ID of device to be accessed.device_info: (output) Pointer to variable storing the result.Return Value:An ibApi_RESULT_SUCCESS if successful, error code (<0) if not.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-91.png)
![4-30 Millennial NetUsing the MeshScape API11. ibApi_IO_GetSerialBufferStatus()ibApi_FUNC ibApi_IO_GetSerialBufferStatus ( ibApi_APIHANDLE api_hdl, ibApi_DEVICEID device_id, ibApi_IOMODE io_mode );For the given device, this function retrieves the status of the out going serial data buffer. The return value gives the number of empty packet slots in the buffer. A negative return value denotes an error and a zero return value means there is currently no out going empty packet slots.Parameters:api_hdl: (input) API handle returned from ibApi_Open().device_id: (input) ID of the device to be accessed.io_mode: (input) Data direction to be accessed.Return Value:The number of empty out going packet slots if successful, or an error code (<0) if not. 12. ibApi_IO_WriteSerial()ibApi_FUNC ibApi_IO_WriteSerial ( ibApi_APIHANDLE api_hdl, ibApi_DEVICEID device_id, ibApi_UINT8 buffer[], ibApi_UINT16 buffer_size );This function writes buffer_size bytes pointed to by the buffer pointer to the specified device handle. Prior to use, the ibApi_FIELDID_USERDATAMODE field must have been configured for serial operation. The specific contents of the user data block and its maximum size are application defined but must be equal to or smaller than that the maximum payload size supported. Maximum payload size supported is returned when the function ibApi_WriteSerialData() is called with buffer_size=0.Parameters:api_hdl: (input) API handle returned from ibApi_Open().device_id: (input) ID of the device to be accessed.buffer: (input) Pointer to packet to transmit.buffer_size: (input) Number of bytes in user data packet to transmit.Return Value:Bytes sent if successful, or an error code (<0) if not.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-106.png)
![RK-5409-5 Reference Kit User’s Guide 4-31iBeanAPI_IO.h13. ibApi_IO_ReadSerial()ibApi_FUNC ibApi_IO_ReadSerial ( ibApi_APIHANDLE api_hdl, ibApi_DEVICEID device_id, ibApi_UINT8 buffer[], ibApi_UINT16 buffer_size, ibApi_UINT8 seq_num );For the given device, this retrieves the user data packet that arrived most recently. The ibApi_IO_SERIALMODE setting must have been previously something other than ibApi_IO_SERIALMODE_DISABLED. The input buffer holds a single packet (i.e., an arriving packet overwrites the previous one). Lost packets can be detected by gaps in the sequence numbers, which increment whenever a packet is received. If no new data is available, then the return value is 0.Parameters:api_hdl: (input) API handle returned from ibApi_Open().device_id: (input) ID of the device to be accessed.buffer[ ]: (output) Buffer to store the incoming user data packet.buffer_size: (input) Maximum size for buffer[ ].seq_num: (output) Sequence number identifying this packet, or NULL if this information is not needed.Return Value:Error code or the actual size of the result (which could exceed buffer_size if the written data was truncated) 14. ibApi_IO_SetDeviceConfigAndDataibApi_FUNC ibApi_IO_SetDeviceConfigAndData( ibApi_APIHANDLE api_hdl, ibApi_DEVICEID device_id, ibApi_deviceSetConfigAndData *config_data);This function is used to make several configuration and data requests to a device at one time.Parameters:api_hdl: (input) API handle returned from @link ibApi_Open()device_id: (input) the ID of the device to be accessedconfig_data: (input) User requested configuration.](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-107.png)
![4-44 Millennial NetUsing the MeshScape API/***************************************************************************/void WaitForKey(void) { printf("\r\nPress any key to close..."); _getch(); printf("\r\n");}/**************************************************************************** * This is a simple wrapper for detecting and reporting API error return * values. In C++, this function could throw an exception object. */ibApi_RESULT CheckResult(ibApi_RESULT result) { char error_text[256]; /* * Error codes always have a negative value. */ if (result >= 0) return result; /* * For the purposes of this example, ibApi_RESULT_ERR_TIMEOUT is not a * fatal error. */ if (result == ibApi_RESULT_ERR_TIMEOUT) return result; /* * This interprets the error code, writing the result to the error_text * variable */ ibApi_Utils_GetErrorDescription(result,error_text,sizeof(error_text)); printf("\r\nERROR: %s\r\n",error_text); /* * Technically, ibApi_Close() should be called before exiting, e.g. via * an atexit() handler. (This is omitted in the example for simplicity.) */ WaitForKey(); exit(1); return 0;}](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-120.png)
![RK-5409-5 Reference Kit User’s Guide 4-45Example API Code/***************************************************************************/void ListDevices(ibApi_APIHANDLE api_hdl) {#define DEVICEIDS_MAX 100 ibApi_GROUPID groupid; ibApi_DEVICEID deviceids[DEVICEIDS_MAX]; int deviceids_count; char deviceid_text[256]; int sampling_interval; int i; ibApi_DEVICEINFO deviceinfo; ibApi_DEVICESTATUS devicestatus; /* * The ibApi_GetNetworkList() function returns a list of the groups * currently managed by the network. If the gateway is not properly * connected to the monitor, then this list will be empty. */ if (CheckResult(ibApi_GetNetworkList(api_hdl,&groupid,1) < 1)) { printf("The network is empty\r\n"); return; } /* * List the gateways in the group, which typically should be * only one. */ printf("\r\nGATEWAYS\r\n"); deviceids_count = CheckResult(ibApi_GetDeviceList(api_hdl, groupid, ibApi_DEVICETYPE_GATEWAY, deviceids,DEVICEIDS_MAX)); /* * If the buffer limit was exceeded, then display partial results */ if (deviceids_count > DEVICEIDS_MAX) deviceids_count = DEVICEIDS_MAX; for (i=0; i<deviceids_count; ++i) { /* * Note that the struct_size must be assigned BEFORE calling * ibApi_GetDeviceInfo(). This allows compatibility with future API * versions that implement additional fields. */ deviceinfo.struct_size = sizeof(deviceinfo);](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-121.png)
![4-46 Millennial NetUsing the MeshScape API CheckResult(ibApi_GetDeviceInfo(api_hdl,deviceids[i],&deviceinfo)); CheckResult(ibApi_Utils_ConvertDeviceIdToText(deviceids[i], deviceid_text,sizeof(deviceid_text),MIN_DEVICEID_WORDS)); printf(" %10s fw=\"%s\" hw=\"%s\"\r\n", deviceid_text, deviceinfo.firmware_version,deviceinfo.hardware_version); } /* * List the mesh nodes. */ printf("\r\nROUTERS\r\n"); deviceids_count = CheckResult(ibApi_GetDeviceList(api_hdl, groupid, ibApi_DEVICETYPE_ROUTER|ibApi_DEVICETYPE_ROUTERBEAN, deviceids,DEVICEIDS_MAX)); if (deviceids_count > DEVICEIDS_MAX) deviceids_count = DEVICEIDS_MAX; for (i=0; i<deviceids_count; ++i) { /* * Note that the struct_size must be assigned BEFORE calling * ibApi_GetDeviceStatus(). */ devicestatus.struct_size = sizeof(devicestatus); CheckResult(ibApi_GetDeviceStatus(api_hdl,deviceids[i],&devicestatus)); CheckResult(ibApi_Utils_ConvertDeviceIdToText(deviceids[i], deviceid_text,sizeof(deviceid_text),MIN_DEVICEID_WORDS)); printf(" %10s (%i hops)\r\n", deviceid_text, devicestatus.hop_count); } /* * List the end nodes. */ printf("\r\nENDPOINTS\r\n"); deviceids_count = CheckResult(ibApi_GetDeviceList(api_hdl, groupid, ibApi_DEVICETYPE_ENDPOINT, deviceids,DEVICEIDS_MAX)); if (deviceids_count > DEVICEIDS_MAX) deviceids_count = DEVICEIDS_MAX; for (i=0; i<deviceids_count; ++i) {](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-122.png)
![RK-5409-5 Reference Kit User’s Guide 4-47Example API Code CheckResult(ibApi_Utils_ConvertDeviceIdToText(deviceids[i], deviceid_text,sizeof(deviceid_text),MIN_DEVICEID_WORDS)); sampling_interval = CheckResult(ibApi_GetSamplingInterval(api_hdl,deviceids[i])); printf(" %10s (%i ms)\r\n", deviceid_text, sampling_interval); }}/***************************************************************************/int main() { /* * This handle represents the current API session. */ ibApi_APIHANDLE api_hdl; ibApi_VERSION api_version; api_version = ibApi_GetApiVersion(); printf("\r\nInitializing API Version %i.%i.%i\r\n\r\n", ibApi_GET_VERSION_MAJOR(api_version), ibApi_GET_VERSION_MINOR(api_version), ibApi_GET_VERSION_RELEASE(api_version) ); /* * ibApi_Open() is called to begin the session. Your application * should ensure that ibApi_Close() is called to release the handle * before exiting. */ api_hdl = CheckResult(ibApi_Open(ibApi_EXPECTED_VERSION,"local","")); ListDevices(api_hdl); CheckResult(ibApi_Close(api_hdl)); WaitForKey(); return 0;}](https://usermanual.wiki/Millennial-Net/URM-G-916/User-Guide-601367-Page-123.png)
