SDI-12 Library
Description
Basic library for the SDI12 add on of the rapidM2MEasy IoT hardware platform.
Overview
Abstract:
This library adds the support for the SDI-12 add on for the rapidM2M EasyIoT. Right now concurrent measurements aren't supported.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT
- Firmware: 01v027 and higher
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Basic_Config:
/* ----------------------------------------------------------------------------
* sdi12-microtronics: Basic Config
* ----------------------------------------------------------------------------
*
* Use this block to adapt the basic configuration settings:
*
* Note: If you want to support more than 10 sensors or use
* addresses outside of the normal address range ('0'-'9')
* SDI12_EXTENDED_ADDRESS_RANGE must be set to 1
* The extended address range is 'A'-'Z' and 'a'-'z'
*/
#define SDI12_SENSOR_CNT_MAX 1 // Maximum number of connected sensors
#define SDI12_EXTENDED_ADDRESS_RANGE 0 // Use extended address range
/** ----------------------------------------------------------------------------
* sdi12-microtronics: Debug Config
* -----------------------------------------------------------------------------
*
* Use this block to configure the debug mode:
*
* 0: No outputs
* 1: Extended debug output
*/
#define SDI12_DEBUG 0
How_to_use:
#define FLAG_SENSOR_FOUND 0x01
#define FLAG_SCANNING 0x02
#define FLAG_MEASURING 0x04
static sApp_Vars[.iFlags, .iSensorAddress];
new iSdi12Handle;
SDI12_EvtResponse(iHandle, iSensorAddr, iEvent, iResult, const aData{}, iLen)
{
if(iSdi12Handle != iHandle)
return;
switch(iEvent)
{
case SDI12_EVT_SCAN_FINISHED:
{
if(iResult >= OK)
{
if(iLen > 0)
{
sApp_Vars.iSensorAddress = aData{0};
sApp_Vars.iFlags |= FLAG_SENSOR_FOUND;
#log("Sensor with address %c found", aData{0});
}
else
{
#log("No sensor found");
}
}
else
{
#log("Scan failed");
}
sApp_Vars.iFlags &= ~FLAG_SCANNING;
}
case SDI12_EVT_DATA_READY:
{
new Float:aRes[9];
if(iResult >= OK)
{
new iNumOfResults = SDI12_GetReceivedData(iSdi12Handle, iSensorAddr, aRes, 9);
for(new i = 0; i < iNumOfResults; i++)
{
#watch("%c:Res%d=%f", iSensorAddr, i, aRes[i]);
}
}
else
{
#log("Error while starting measurement or reading data from sensor");
}
}
}
}
#callback MainTimer1s()
{
if(!(sApp_Vars.iFlags & FLAG_SENSOR_FOUND || sApp_Vars.iFlags & FLAG_SCANNING))
{
SDI12_Scan(iSdi12Handle);
sApp_Vars.iFlags |= FLAG_SCANNING;
}
else if(!(sApp_Vars.iFlags & FLAG_MEASURING))
{
if(SDI12_Measure(iSdi12Handle, sApp_Vars.iSensorAddress) >= OK)
sApp_Vars.iFlags |= FLAG_MEASURING;
}
}
main()
{
SDI12_Init(iSdi12Handle, SDI12_INTERFACE_1);
sApp_Vars.iFlags = 0;
sApp_Vars.iSensorAddress = -1;
setInterval(MainTimer1s, 1000);
}
Basic
SDI12_Init(&iHandle, iInterface)
Initialises the specified interface to use for SDI-12 communication.
iHandle : s32 - Empty iHandle for a SDI-12 communication interface
iInterface : s32 - Serial interface that should be used for the SDI-12 communication (use SDI12_INTERFACE_x)
returns : Terror
OK - if successful
ERROR - if
interface already initialized
interface not supported
ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
< OK - if an error occured
When using SDI12 a callback function must be added to DLO which must be named SDI12_EvtResponse.
SDI12_Close(&iHandle)
Closes the specified interface to use for SDI-12 communication.
iHandle : s32 - Handle for a SDI-12 communication interface to close
returns : Terror
OK - if successful
ERROR - if interface not supported
ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
< OK - if an error occured
SDI12_Scan(iHandle)
Starts a scan of all addresses till either SDI12_SENSOR_CNT_MAX sensors were found or the maximum address was reached. If SDI12_EXTENDED_ADDRESS_RANGE is set to 1 the normal as well as the extended address ranges are scanned, else only the normal address range.
iHandle : s32 - Handle for the SDI-12 communication interface
returns : Terror
OK - if successful
< OK - if an error occured
The normal address range is '0'-'9'
The extended address range is 'A'-'Z' and 'a'-'z'
After the scan has finished the DLO is informed via SDI12_EvtResponse with the event type SDI12_EVT_SCAN_FINISHED. aData contains the addresses of the found sensors and iLen the number of found sensors.
SDI12_Measure(iHandle, iAddr)
Sends "Start Measurement" to the sensor with the given address.
iHandle : s32 - Handle for the SDI-12 communication interface
iAddr : s32 - Address of the sensor to send the command to
returns : Terror
OK - if successful
ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
< OK - if an error occured
After the measurement finished and the data was received the DLO is informed via SDI12_EvtResponse with the event type SDI12_EVT_DATA_READY. To get the data SDI12_GetReceivedData must be called.
SDI12_GetReceivedData(iHandle, iSensorAddr, aResult[], iMaxNum)
Get the latest received measured data from the specified sensor
iHandle : s32 - Handle for the SDI-12 communication interface
iSensorAddr : s32 - Address of the sensor to get the data from
aResult : Float - Variable to store the received data
iMaxNum : s32 - Number of maximum results to return
returns : Terror
>= OK - Number of results returned
< OK - if an error occured
SDI12_EvtResponse(iHandle, iSensorAddr, iEvent, iResult, const aData{}, iLen)
Function to be provided by the device logic developer, that is called when certain SDI-12 events happen.
iHandler : s32 - Handle of the SDI-12 communication interface on which the event happened
iSensorAddr : u8 - Address of the sensor where the event happened
In case of the event SDI12_EVT_SCAN_FINISHED this address is allways 0.
iEvent : SDI12_EVT_xxx - SDI12 event type
iResult : Terror - Result of the operation
OK - Command successfull
OK - if an error occured
aData{} : u8 - Data depending on the event
iLen : s32 - Length of the data
SDI12_EVT_xxx:
SDI12_EVT_SCAN_FINISHED = 0 - Scan for connected sensors has finished
SDI12_EVT_DATA_READY = 1 - All data received from the sensor
SDI12_INTERFACE_x: s32
Serial interface of the device that can be used for SDI-12 communication
SDI12_INTERFACE_1 = 0 - first RS232 interface
SDI12_INTERFACE_CNT = 1 - Number of usable serial interfaces