Thing / Device
Looking for the Cloud TCP Proxy Documentation? CLICK_THIS_LINK
Platform Functions
The following sections will describe the available functionality of the Cloud Connect Device Application Platform.
Prerequisites
1ms tick timer
For the Device Application Platform to function, it needs to be provided with a 1 millisecond timer tick that drives the platform, contact Telenor Connexion for info.
Cloud Connect Passport (CC2.0 Specific)
For the device to be able to connect to the Cloud Connect 2.0 platform, a
Cloud Connect Passport must have been installed on the file system of the External SPI Flash of the Gateway.
The Cloud Connect Passport contains the server address to connect to, the root certificate for the AWS IOT
Service, the device certificate and the device private RSA key.
For the device to be able to use this certificate, it must use a library that handles file system access to the external SPI-Flash and the following code must be added to the startup procedure, preferably to the Main.c-file.
If normal production firmware, this is enough, since the passport will have been installed during production:
FS_FileSystemInit();
if(CCP_OpenPassport() < 0)
{
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Error opening passport.")); // This is optional but useful for debug purposes.
}
else
{
extern const u8 * ccp_p_thing_id;
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Passport opened OK.")); // This is optional but useful for debug purposes.
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Thing ID: %s", ccp_p_thing_id)); // This is optional but useful for debug purposes.
}
Threads
ETIF threads is a collection of macros for easy creation of threaded applications
inside the framework. Enabling stackless cooperative multitasking, providing
linear code execution for event-driven systems implemented in C.
Threads are added using ETIF_ADD_THREAD(Application) in ETIF_AppRegistry.h
ETIF_ADD_THREAD()
For documentation, see ETIF_THREAD_BEGIN
Thread types
There are two types of threads that may exist
NOCHILD - This is a thread that does not invoke new threads, i.e. no child.
PARENT - This is a thread that may invoke a new child thread.
ETIF_THREAD_BEGIN(Child)
Declare a thread.
This function is used to declare the starting point of a thread. It is usually
placed at the beginning of the function in which the thread runs. The function
must always have a matching ETIF_THREAD_END().
Due to the way this threaded scheme is implemented a few ground rules need to be considered:
- Local variables that need to keep their value through thread scheduling needs
to be declared as
static. - Thread constructors and control macros can normally not be used inside a switch/case section.
- All C statements above the
ETIF_THREAD_BEGINinvocation will be executed each time the thread is scheduled.
Parameters
Child - Shall be set to NOCHILD or PARENT depending on if the thread shall be
able spawn sub threads.
Example usage
First register your application thread in the ETIF_AppRegistry.h in the P_ETIF_THREAD_SCHEDULER_H section.
ETIF_ADD_THREAD(MyApplication)
Then write your application thread.
tETIF_THREAD MyApplication(mETIF_THREAD_MESSAGE)
{
//
// Here put code you want to run each time this thread is scheduled
//
ETIF_THREAD_BEGIN(NOCHILD);
//
// Here put code you want to run only the first time the thread is run,
// initialization etc.
//
while(1) // If you don't want the thread ever to
// end. Make a continues loop inside the
{ // thread. Usually the case of the main
// thread of an application.
ETIF_THREAD_WAIT_UNTIL(kbhit()); // Wait for data input, CPU time is
// yielded to other application threads
switch(getch()) // while waiting.
{
//
// Do something with the received input......
//
}
}
ETIF_THREAD_END();
}
ETIF_THREAD_END()
Declare the end of a thread.
This macro is used for declaring that a thread ends. It must always be
used together with a matching ETIF_THREAD_BEGIN() macro.
It terminates the thread and de-allocates all associated memory if dynamic memory allocation
is enabled (Not yet implemented :-)).
Timer Events
ETIF_THREAD_TIMER_EVENT_BEGIN(Func)
Declares the start of a timer event thread.
This macro is used to declare the starting point of a timer event thread. It should be placed at the start of the function in which the thread runs.
All C statements above the ETIF_THREAD_TIMER_EVENT_BEGIN() invocation will
be executed each time the thread is scheduled. This macro must always be used
together with a matching ETIF_THREAD_TIMER_EVENT_END(). In contrast to
ETIF_THREAD_BEGIN() the ETIF_THREAD_TIMER_EVENT_BEGIN() implements a timer
event driven thread that runs with a defined periodicity and that is started and
stopped from user application. The use if ETIF_THREAD_DELAY() or thread time-out
feature are not supported within a timer event thread.
The prototype of a function implementing a timer event must be declared like this:
tTimerEventRet MyTimerEventThread(tTimerEventParam)
An implementation of such a timer event function can be controlled by calling it with one of the following commands.
ETIF_TIMER_EVENT_SET
Example usage
MyTimerEventThread(ETIF_TIMER_EVENT_SET, 1000);
ETIF_TIMER_EVENT_SSH
Starts a single shot timer event triggering one execution of the event after a time specified in milliseconds from from the time it is set.
Example usage
MyTimerEventThread(ETIF_TIMER_EVENT_SSH, 1000);
ETIF_TIMER_EVENT_STP
Cancels an active timer event before it is executed. No more events will occure. The internal states of the event will also be reset for a fresh start next time the event is started.
Example usage
MyTimerEventThread(ETIF_TIMER_EVENT_STP);
Parameters
Func - The name of the function implementing the timer event thread.
NOTE. Any running instance of the timer event will be canceled before a new instance
is activated through any of the set commands.
Example usage
/****************************************************************************
* *
* T H E T I M E R E V E N T T H R E A D *
* *
****************************************************************************/
tTimerEventRet MyTimerEventThread(tTimerEventCmd Cmd, ...)
{
//
// Here put code you want to run each time this thread is scheduled
//
ETIF_THREAD_TIMER_EVENT_BEGIN(MyTimerEventThread);
//
// Here put code you want to run only the first time the thread is run,
// initialization etc.
//
if(kbhit())
{
switch(getch())
{
//
// Do something with the received input......
//
}
}
ETIF_THREAD_TIMER_EVENT_END();
/**************************** End of function ******************************/
}
/****************************************************************************
* *
* T H E M A I N A P P L I C A T I O N T H R E A D *
* *
****************************************************************************/
void MainApplication(void)
{
EVENT_THREAD_PERIODICITY 3000
ETIF_THREAD_BEGIN();
MyTimerEventThread(ETIF_TIMER_EVENT_SET, EVENT_THREAD_PERIODICITY); // Start the timer event thread.
// From now on the timer event
while(1) // thread will run with a periodicity
{ // specified by EVENT_THREAD_PERIODICITY.
// Main thread code.
}
ETIF_THREAD_END();
/*************************** End of function *****************************/
}
ETIF_THREAD_TIMER_EVENT_END()
Declare the end of a timer event thread.
This macro is used for declaring end of a timer event thread. It must always be
used together with a matching ETIF_THREAD_TIMER_EVENT_BEGIN()
It terminates the thread and deallocates all associated memory if dynamic memory
allocation is enabled (Not yet implemented :-)).
For usage example, see ETIF_THREAD_TIMER_EVENT_BEGIN
ETIF_THREAD_WAIT_UNTIL(condition)
Block and wait until condition is true.
This macro blocks the thread until the specified condition is true. Meanwhile CPU time is yielded to other threads.
Parameters
condition - The conditional statement.
Example Usage
ETIF_THREAD_WAIT_UNTIL( Level > UPPER_LEVEL); // Stay here while the level is below max level.
ETIF_THREAD_SPAWN()
Spawn a child thread.
This macro spawns a child thread and blocks until it exits. The macro can
only be used within a thread. A sub thread can in turn spawn yet another
subthread. The PARENT thread will be blocked until it´s child terminates.
Parameters
thread - The child thread with arguments
Example code
tETIF_THREAD MySubThread(mETIF_THREAD_MESSAGE, u8 SomeParameter)
{
ETIF_THREAD_BEGIN(NOCHILD);
:
:
:
ETIF_THREAD_END();
}
tETIF_THREAD MyApplication(mETIF_THREAD_MESSAGE)
{
ETIF_THREAD_BEGIN(PARENT);
:
:
ETIF_THREAD_SPAWN(MySubThread, aParameter);
:
:
ETIF_THREAD_END();
}
ETIF_THREAD_YIELD()
Yield CPU time to other threads.
Due to the cooperative nature of multitasking provided by ETIF_Threads threads need to yield CPU time to other threads.
This function will let the current thread yield, thereby allowing other
threads to get some CPU time. Other functions like ETIF_THREAD_DELAY()
and ETIF_THREAD_WAIT_UNTIL() also yields.
Parameters
none
Example Code
while(1)
{
if(ChkTimer(hTimer1))
{
break;
}
if(ChkTimer(hTimer2))
{
break;
}
ETIF_THREAD_YIELD(); // Let the rest of the system do something
// useful while we are waiting.
}
ETIF_THREAD_DELAY(Time)
Thread delay.
Make a delay in the program flow in a thread. Meanwhile CPU time is yielded to other threads.
This macro is used when the application needs to delay the progress in the code execution in a thread for a certain amount of time.
This delay is NON BLOCKING, meaning that other threads can keep doing their thing while the thread using ETIF_THREAD_DELAY() is waiting.
Parameters
Time - Delay time in mS (Max 65535).
// Example Usage
tETIF_THREAD Application(mETIF_THREAD_MESSAGE)
{
ETIF_THREAD_BEGIN(NOCHILD); // Thread with no subtreads
while(1)
{
BlinkLED();
ETIF_THREAD_DELAY(2000); // Will delay the thread for 2000 milliseconds
}
ETIF_THREAD_END();
}
In the example above, no No ETIF_THREAD_YIELD() is necessary due to ETIF_THREAD_DELAY contains YIELD functionality.
ETIF_THREAD_SLEEP(Time)
Thread sleep.
Puts the current thread in to sleep for a requested amount of seconds. In contrast
to ETIF_THREAD_DELAY(), ETIF_THREAD_SLEEP() grants the hardware platform to
enter low power sleep. Be ware of that depending on the underlying hardware platform
the system may or may not be able to receive incoming data or react on external events
when during low power sleep.
Parameters
Time - Sleep time in seconds (Max 65535).
Example Code
Typical implementation of sleep in a thread.
tETIF_THREAD(MyThread)
{
static tSleepHnd hSleep; // Since the thread is yielded while
: // timer is running the handle variable
: // must be static.
ETIF_THREAD_BEGIN();
while(1)
{
:
ETIF_THREAD_SLEEP(10); // Delay the thread 10 Seconds and allow
: // the system to enter low power mode
: // during this time.
:
Do something
:
:
:
:
}
ETIF_THREAD_END();
/************************* E N D O F F U N C T I O N **********************/
}
Thread timeout.
ETIF_THREAD_TIMEOUT_BEGIN(TimeOut)
This macro sets up a procedural timeout for a thread. If the thread procedur is
not finished executing within this time it will be terminated and control returned
to its caller. The function must always have a matching ETIF_THREAD_TIMEOUT_END().
Parameters
TimeOut - Timeout time in mS. Max time 15300000 milliseconds (255 minutes).
Example Code
tETIF_THREAD SubThread_WithProcedureTimeOut(tPtChild *pts_parm, tThreadTimeOut TheTimeOut)
{
ETIF_THREAD_BEGIN(NOCHILD);
ETIF_THREAD_TIMEOUT_BEGIN(TheTimeOut); // Initialise thread procedure time-out.
ETIF_THREAD_WAIT_UNTIL(ETIF_FLAG_CHK(APP_TIMER_EVENT_HAS_HAPPEND));
ETIF_FLAG_RES(APP_TIMER_EVENT_HAS_HAPPEND);
printf("The event happened before the thread timeout was released.");
ETIF_THREAD_TIMEOUT_CATCH: // Catch thread procedure time-out event.
printf(ETIF_DEBUG_TRACE, ("Thread timed out before the event happened.");
ETIF_THREAD_TIMEOUT_END(); // Exit thread procedure time-out.
ETIF_THREAD_END();
/******************************* End of thread ********************************/
}
The use of this macro is linked to the invocation of subthreads.
If the application wants a subthread driven task to finish within a certain time frame, this macro is used together with ETIF_THREAD_TIMEOUT_CATCH(), ETIF_THREAD_TIMEOUT_RESET() and ETIF_THREAD_TIMEOUT_END()
ETIF_THREAD_TIMEOUT_CATCH()
Thread timeout catch.
This statement begins a section where a timeout event can be catched .
Parameters
None
Example Code
For an example see ETIF_THREAD_TIMEOUT_BEGIN().
ETIF_THREAD_TIMEOUT_RESET()
Thread timeout reset.
Restarts current thread time out started with ETIF_THREAD_TIMEOUT_BEGIN();
to its original value.
ETIF_THREAD_TIMEOUT_END()
Thread timeout exit.
This function exits the thread timeout monitored section started with
ETIF_THREAD_TIMEOUT_BEGIN();
ETIF_THREAD_HALT()
ETIF Thread halt.
Used if you wish to halt the execution of a thread usually for debugging purposes.
Cloud Functions
Resources
The resource directory is hosting the resources of a device endpoint or node. A resource in this context is some kind of measured value or configuration settings exposed by a device for a remote client to reading from, subscribe or write to. Typical resources would be Temperature, Pressure, GPS coordinates etc.
The concept of resources can be described by these significant denominators:
Resources can be both virtual or connected to the magnitude of a physical measurement
Physical resources are created by the device connector, virtual resources are generally created in the cloud environment.
A resource can contain almost any type of data, Char, uChar, Int, uInt, Long, uLong, Str etc.
All resources are communicated using ASCII, Application decides whether a conversion from storage class to string value is done or if the resource is sent “as is”
Instances
The system allows for a number of instances of each resource, each containing a collection of all the defined resources.
Each instance will allocate RAM for one set of all the added resources.
Consider that you have the following scenario:
#define ETIF_APP_RESOURCES_NUMBER_OF_INSTANCES 4
ETIF_ADD_APP_RESOURCE(temp, s8, 1, na, 123, 2, EventHandler) // Signed 8 bit integer
ETIF_ADD_APP_RESOURCE(counter, u32, 1, na, 654321, 0, EventHandler) // Unsigned 32 bit integer
ETIF_ADD_APP_RESOURCE(string, c8, 30, na, "Hello world", 1, EventHandlerString) // ASCII String, max 30 chars.
This will allocate 1 + 4 + 30 bytes of RAM for each instance.
Having 4 instances of the above resources will use 140 bytes of RAM.
Note 1: When setting up the instances, the Default instance counts as one instance. (The instance with the default values for the resources)
Note 2: Resources may only contain lower_case letters due to when they are handled in the cloud, all letters are converted to lower case. This means that when the cloud tries to SET a resource in the device, the SET operation sends the resource name as lower case letters and the device will not find it in it´s directory if it was registered containing UPPER_CASE letters.
Add a resource.
ETIF_ADD_APP_RESOURCE( NAME, DATA_TYPE, RESOURCE_SIZE, UCUM, DEFAULT_VALUE, DEFAULT_THRESHOLD, EVENT_HANDLER)
Parameters
Note This is a macro, hence, the parameters do not have a specified type.
| Parameter name | Description |
|---|---|
| NAME | Name of resource in lower case letters |
| DATA_TYPE | The resource data type. |
| RESOURCE_SIZE | - |
| UCUM | Resource unit of measurement.(not used) |
| DEFAULT_VALUE | Resource default value. |
| DEFAULT_THRESHOLD | Resource threshold that must be exceeded in order for the resource to be sent to cloud |
| EVENT_HANDLER | Resource event handler |
Example Code:
Inside the ETIF_RESOURCES section in the ETIF_AppRegistry.h header file, resources may be added like this:
ETIF_ADD_APP_RESOURCE(temp, s8, 1, na, 123, 2, EventHandler) // Signed 8 bit integer
ETIF_ADD_APP_RESOURCE(counter, u32, 1, na, 654321, 0, EventHandler) // Unsigned 32 bit integer
ETIF_ADD_APP_RESOURCE(string, c8, 30, na, "Hello world", 1, EventHandlerString) // ASCII String, max 30 chars.
Resource Directory I/O
eEtifResourceEventCommands
| Command | Description |
|---|---|
| ETIF_RESOURCE_CHANGED | Indicates to user device application that resource has been set to new value by cloud application. |
| ETIF_RESOURCE_FETCHED | |
| ETIF_RESOURCE_SENT | Indicates that the resource has been sent to remote server. |
| ETIF_RESOURCE_NOT_SENT | Indicates that the resource was not sent |
| ETIF_RESOURCE_ALL_SENT | Indicates that all resources has been acknowledged by the remote server. |
| ETIF_RESOURCE_EDGE_CONNECT | Indicates that connections to cloud edge is established. |
| ETIF_RESOURCE_EDGE_LOST | Indicates that connections to cloud edge has been lost. |
eEtifResourceResultCodes
| Result Code | Description |
|---|---|
| ETIF_RESOURCE_OPERATION_OK | The operation on the resource was successfully executed.(Not used. In fact a positive return value indicates a positive result and the value |
| ETIF_RESOURCE_NOT_FOUND | The resource requested for operation not found. |
| ETIF_RESOURCE_FULL | The resource buffer full. Client connection probably down. |
| ETIF_RESOURCE_DESTINATION_TO_SMALL | The chosen destination for a resource get is to small or wrong type. |
| ETIF_RESOURCE_NO_MORE_INSTANCES_AVAILABLE | There are no more resource instances available. |
Data types
| Data type | Description / Size |
|---|---|
| c8 | 8 bits ASCII |
| u8 | 8 bits unsigned int |
| u16 | 16 bits unsigned int |
| u32 | 32 bits unsigned int |
| u64 | 64 bits unsigned int |
| s8 | 8 bits signed int |
| s16 | 16 bits signed int |
| s32 | 32 bits signed int |
| s64 | 64 bits signed int |
| float | 32 bits float |
| double | 64 bits float |
UCUM
The Unified Code for Units of Measure is a code system intended to include all units of measures being contemporarily used in international science, engineering, and business. The purpose is to facilitate unambiguous electronic communication of quantities together with their units. Not yet Implemented
Resource Size
The resource size is added as the number of instances of the type resource type.
Examples:
Resource size 2 for a u32 adds an array of 2 u32 values.
Resource size 32 for a c8 adds space for a string of maximum 32 characters.
Threshold
The resource threshold parameter tells the resource directory how much a resource must be changed in order for it to be sent to the cloud or the event handler when the application or the cloud makes changes to it.
Examples:
Threshold = 0 for any type means that an event is triggered regardless of what the new value is.
Threshold != 0 for all numerical types means that the value of the parameter must change by at least the threshold value for an event to occur.
Threshold != 0 for a c8 resource means that any change in the string triggers an event.
Event Handler
The event handler is registered when adding the resource and is called upon when there is any activity for the resource in question. Many resources can share the same resource event handler. The event Handler should handle at least one of the eEtifResourceEventCommands
Example Code:
/*******************************************************************************
* *
* R E S O U R C E E V E N T H A N D L E R *
* *
*******************************************************************************/
u8 ResourceEventHandler(tEtifResourceEventCommands Cmd, c8 *pPrefix, tETIF_RESOURCE_ID Resource)
{
u16 temp;
if(Cmd == ETIF_RESOURCE_CHANGED)
{
switch(Resource)
{
case getparamlist:
ETIF_ResourceGet(DEFAULT, getparamlist, NewResourceList);
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource: %u was %s, New: %x", Resource, Cmd == ETIF_RESOURCE_CHANGED ? "changed" : "fetched", NewResourceList));
break;
case register_list:
char buffer[CFG_REGISTERS_LIST_MAX_SIZE];
ETIF_ResourceGet(DEFAULT, register_list, buffer); // Fetch new version of the register_list to store it in NV memory
NCFG_SetData_String(cfg_registers_list, buffer, CFG_REGISTERS_LIST_MAX_SIZE)
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("New registers list = %s", NCFG_GetPointer_String(cfg_registers_list)));
NCFG_SaveToNvm(); // Save updated config field.
break;
default:
ETIF_ResourceGet(DEFAULT, Resource, IntRegisterSettings);
break;
}
}
return(0);
/*********************** End of ResourceEventHandler **************************/
}
ETIF_ResourcePut()
Put resource value to resource registry.
Used to update the current value of given resource.
This does not mean that the resource value that was put will be sent to the cloud.
The resource registry evaluates if the new value meets the requirements to be sen to cloud, and if the requirements are met (value more different to old value than threshold) the new value will be sent to the cloud application after the time set by ETIF_NOTIFICATION_DELAY has elapsed since the last time ETIF_ResourcePut() was called.
The flow of an upstream resource event looks like this:
Parameters
This function is implemented as a macro, hence, some parameters do not have a specified type.
| Parameter name | Description |
|---|---|
| InstanceName | The name of the instance to update |
| ResourceName | The name of the resource to update as given when created with ETIF_ADD_APP_RESOURCE |
| DataSrc | Pointer to new value for the resource of the same type given when creating the resource with ETIF_ADD_APP_RESOURCE |
Returns:
One of the eEtifResourceResultCodes
Example Code:
ETIF_ResourcePut(myinstance, myresource, (u16 *) &Value);
ETIF_ResourceGet()
Get resource value.
Used to get the current value of given resource from the resource registry.
This does not mean that the cloud value of the resource is fetched from the cloud!!
The flow for a complete - all the way from server to device - downstream resource event looks like this:
First the server issues a SET command to the device:
If an event handler has been configured for the resource an event vill be given when the resource has been updated and the application can now GET the new value from the device resource directory using ETIF_ResourceGet()
Parameters
This function is implemented as a macro, hence, some parameters do not have a specified type.
| Parameter name | Description |
|---|---|
| InstanceName | The name of the instance to get the resource for |
| ResourceName | The name of the resource to get when created with ETIF_ADD_APP_RESOURCE() |
| Destination | Destination for value fetched of the same type as the resource to be fetched. |
Returns
One of the eEtifResourceResultCodes
Example Code:
ETIF_ResourceGet(myinstance, myresource, (char *) &Value); // fetch the resource "myresource" for the instance "myinstance" from the resource directory.
FTP Functionality
Firmware update
The Firmware of the device can be updated by downloading a new firmware from an FTP by using passive mode.
mainFirmwareDownload()
Is used for downloading and changing to a different firmware.
Note 1: If the GPS stream is used in the application, make sure that the GPS stream is not started before doing FW upgrade, in order to avoid Checksum corruption issues.
Note 2: It is advised that the application threads are halted using ETIF_THREAD_HALT() during FW Download, in order to avoid Checksum corruption issues.
Example Usage:
mainFirmwareDownload("ftp://fwftp.no-ip.org:50000/TST_V010102_DL.bin");
File Upload
File Upload is done using ETIF_Resource_PutFile(target, Eventhandler)
In order to supply the application with the parameters for file upload, it is recommended that a fileupload resource is added to the application. When a file needs to be uploaded, the cloud can now set the fileupload resource to a string containing all the info that ETIF_Resource_PutFile target needs to complete the task.
Example add file upload resource:
ETIF_ADD_APP_RESOURCE(fileupload, c8, 100, NON, "", 0, ResourceEventHandler)
Example handle fileupload resource in ResourceEventHandler:
/*******************************************************************************
* *
* R E S O U R C E E V E N T H A N D L E R *
* *
*******************************************************************************/
u8 ResourceEventHandler(tEtifResourceEventCommands Cmd, c8 *pPrefix, tETIF_RESOURCE_ID Resource)
{
union { u8 u8Val; u16 u16Val; u32 u32Val; s8 s8Val; s16 s16Val; s32 s32Val; float floatVal; double doubleVal; c8 stringVal[100]; }Local;
switch(Cmd)
{
case ETIF_RESOURCE_CHANGED:
switch(Resource)
{
case fileupload:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("%s/%s, was %s", pPrefix, ETIF_ResourceNameGet(Resource), Cmd == ETIF_RESOURCE_CHANGED ? "changed" : "fetched"));
ETIF_ResourceGet(pPrefix, fileupload, Local.stringVal);
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("New value %s", Local.stringVal));
ETIF_Resource_PutFile(Local.stringVal, FileUploadEvent); // Start file upload procedure.
break;
break;
case ETIF_RESOURCE_SENT:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s threshold exceeded, sent to cloud!", ETIF_ResourceNameGet(Resource)));
break;
case ETIF_RESOURCE_NOT_SENT:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s threshold was not exceeded, not sent to cloud!", ETIF_ResourceNameGet(Resource)));
break;
default:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s unhandled event %u", ETIF_ResourceNameGet(Resource), Cmd));
break;
}
return(0);
/*********************** End of ResourceEventHandler **************************/
}
Parameters
| Parameter | Description |
|---|---|
| Target | A string containing the URI for an FTP server, including user, password, domain, port and filename. |
| EventHandler | A function that handles the events that is generated by the call to ETIF_Resource_Putfile, handles three of the eEtifResourceResultCodes |
eEtifResourceResultCodes handled by File Upload Event Handler
| Result Code | Description |
|---|---|
| ETIF_RESOURCE_FILE_TRANSFER_ERROR | File transfer ended in error |
| ETIF_RESOURCE_FILE_EMPTY | File transmit empty buffer |
| ETIF_RESOURCE_SESSION_END | FTP Session ended successfully |
Example Usage:
The example shows the upload of 2000 rows of the same line of text.
The application can substitute this with any data and feed it to the Upload machinery with a maximum of 1500 bytes/chunk, the data in question can for example be read from a non volatile storage to a temporary buffer that is pointed to using the pBuffer pointer.
First create the Eventhandler
/*******************************************************************************
* *
* F I L E U P L O A D E V E N T H A N D L E R *
* *
*******************************************************************************/
u8 FileUploadEvent(s8 Cmd, u8 **pBuffer, u32 *Nb)
{
RECORDS_TO_SEND 2000
static u32 RecordsSent=0;
static u32 TotNb=0;
static u8 Record[100];
switch(Cmd)
{
case ETIF_RESOURCE_FILE_EMPTY:
if(RecordsSent++ < RECORDS_TO_SEND)
{
snprintf((c8 *)Record, sizeof(Record), "\r\n%.06u "ETIF_FOX_MESSAGE, RecordsSent);
*pBuffer=&Record[0]; // This tells the file upload machinery where to find the data to upload.
*Nb=strlen((c8 *) Record); // This tells the file upload machinery how many bytes that are available.
TotNb+=*Nb;
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE,("Send record no: %u total number of bytes %lu", RecordsSent, TotNb));
}
else
{
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE,("End of file, total number of bytes sent %lu", TotNb));
*Nb=0; // When the file upload machinery is told that there is no bytes, the upload procedure is ended.
}
break;
case ETIF_RESOURCE_FILE_TRANSFER_ERROR:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("File upload ended in error!"));
RecordsSent=0;
break;
case ETIF_RESOURCE_SESSION_END:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("FTP Session ended - successfully!"));
RecordsSent=0;
break;
}
return(OK);
/************************ End of FileTransmitEvent ****************************/
}
Then make the call to the ETIF_Resource_PutFile:
ETIF_Resource_PutFile("ftp://server:port/TestPutFile.txt", FileUploadEvent);
File Download
File Download is done using ETIF_Resource_GetFile(target, Eventhandler)
In order to supply the application with the parameters for file download, it is recommended that a filedownload resource is added to the application. When a file needs to be downloaded to the device, the cloud can now set the filedownload resource to a string containing all the info that ETIF_Resource_GetFile target needs to complete the task.
Example add file Download resource:
ETIF_ADD_APP_RESOURCE(filedownload, c8, 100, NON, "", 0, ResourceEventHandler)
Example handle download resource in ResourceEventHandler:
/*******************************************************************************
* *
* R E S O U R C E E V E N T H A N D L E R *
* *
*******************************************************************************/
u8 ResourceEventHandler(tEtifResourceEventCommands Cmd, c8 *pPrefix, tETIF_RESOURCE_ID Resource)
{
union { u8 u8Val; u16 u16Val; u32 u32Val; s8 s8Val; s16 s16Val; s32 s32Val; float floatVal; double doubleVal; c8 stringVal[100]; }Local;
switch(Cmd)
{
case ETIF_RESOURCE_CHANGED:
switch(Resource)
{
case filedownload:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("%s/%s, was %s", pPrefix, ETIF_ResourceNameGet(Resource), Cmd == ETIF_RESOURCE_CHANGED ? "changed" : "fetched"));
ETIF_ResourceGet(pPrefix, filedownload, Local.stringVal);
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("New value %s", Local.stringVal));
ETIF_Resource_GetFile(Local.stringVal, FileDownloadEvent); // Start file download procedure.
break;
}
break;
case ETIF_RESOURCE_SENT:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s threshold exceeded, sent to cloud!", ETIF_ResourceNameGet(Resource)));
break;
case ETIF_RESOURCE_NOT_SENT:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s threshold was not exceeded, not sent to cloud!", ETIF_ResourceNameGet(Resource)));
break;
default:
ETIF_DEBUG_STR(ETIF_DEBUG_TRACE, ("Resource %s unhandled event %u", ETIF_ResourceNameGet(Resource), Cmd));
break;
}
return(0);
/*********************** End of ResourceEventHandler **************************/
}
Parameters
| Parameter | Description |
|---|---|
| Target | A string containing the URI for an FTP server, including user, password, domain, port and filename. |
| EventHandler | A function that handles the events that is generated by the call to ETIF_Resource_Getfile, handles three of the eEtifResourceResultCodes |
eEtifResourceResultCodes handled by File Download Event Handler
| Result Code | Description |
|---|---|
| ETIF_RESOURCE_NOT_SET | Is generated when there is data to handle |
| ETIF_RESOURCE_FILE_EMPTY | File transmit empty buffer |
| ETIF_RESOURCE_SESSION_END | FTP Session ended successfully |
Example Usage:
The example shows the download process, without storing anything of a file
The application can substitute this with handling that stores the downloaded data to non volatile storage.
First create the Eventhandler:
/*******************************************************************************
* *
* F I L E D O W N L O A D E V E N T H A N D L E R *
* *
*******************************************************************************/
u8 FileDownloadEvent(s8 Cmd, u8 *pBuffer, u16 Nb)
{
static u32 Total=0;
static tTimerHnd hMyTimer;
switch(Cmd)
{
case 0:
Total+=Nb;
ETIF_DEBUG_BIN(ETIF_DEBUG_TRACE, ("Received %u total %lu", Nb, Total), pBuffer, Nb);
break;
case ETIF_RESOURCE_FILE_TRANSFER_ERROR:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("File download ended in error!"));
break;
case ETIF_RESOURCE_SESSION_END:
Total+=Nb;
ETIF_DEBUG_BIN(ETIF_DEBUG_TRACE, ("End of file transfer, received %u total %lu", Nb, Total), pBuffer, Nb);
Total=0;
break;
}
ETIF_TimerSet(&hMyTimer, (Nb*2)/8); // Delay to make trace output to have time to get out.
while(ETIF_TimerChk(&hMyTimer));
return(OK);
/************************ End of FileDownloadEvent ****************************/
}
Then make the call to the ETIF_Resource_GetFile: ETIF_Resource_GetFile(“ftp://server:port/TestFile.txt", FileDownloadEvent);
Stream functions
ETIF streams are used for generalizing serial I/O for network, file or memory read/write as well as other devices that are accessed in a sequential way.
Stream types
There are a number of supported stream types.
NOTE When using streams; The following conditions currently apply:
| Serial stream usage scenario | Condition |
|---|---|
| GWMGR + App socket + one serial stream | None |
| GWMGR + App socket + two serial streams | GWMGR + APP Socket must be opened before opening serial stream |
| GWMGR + App socket + GPS Stream + one serial stream | GWMGR + APP Socket + GPS Stream must be opened before opening serial stream |
| GWMGR + App socket + GPS Stream + two serial streams | NOT POSSIBLE |
Serial Streams
Currently there are two supported serial stream types.
| Stream type | Description |
|---|---|
| RS485 | Half duplex serial port with RX/TX enable control |
| serial | Any type full duplex serial communication using normal USART functionality |
Serial stream configuration
The serial streams can be configured in regard to the number of data bits, stop bits, parity and baud rate.
The supported and not supported combinations are listed int the table below.
All baud rates are allowed.
| Data bits | Stop bits | Parity | Supported |
|---|---|---|---|
| 8 | 1 | none | OK |
| 8 | 2 | none | OK |
| 7 | 1 | none | Not supported |
| 7 | 2 | none | Not supported |
| 8 | 1 | Odd or Even | OK |
| 8 | 2 | Odd or Even | OK |
| 7 | 1 | Odd or Even | OK |
| 7 | 2 | Odd or Even | OK |
When setting up the serial stream, parity is according to table below.
| Parity type | Parameter value |
|---|---|
| None | N / n |
| Odd | O / o |
| Even | E / e |
Example usage
static tStreamHnd hRS485=0;
// Set up stream with 9600bps baud rate, 8 data bits, 2 stop bits and Even parity.
ETIF_StreamClientOpen(&hRS485, "RS485://uart0,9600,8,2,E", 0, StreamEvent_ExternalRS485);
TCP Streams
Currently, TCP ethernet streams are supported.
GPS Stream
For devices that are GPS Enabled, the GPS Stream is available.
ETIF_STREAM_ADD()
Is used to add a stream to the registry of available streams to make it available for the application to use.
The streams are added in ETIF_AppRegistry.h.
Currently streams need to be added when creating the library that contains the ETIF functionality.
ETIF_StreamClientOpen(hStream, StreamURI, AccessMode, StreamHandler)
Is used for opening a stream client.
Parameters
| Parameters | Description |
|---|---|
| hStream | Pointer to the stream handle used by the caller to refer to the stream. Set to a positive value between 1-127. Negative value indicates a stream creation error. |
| StreamURI | StreamURI URI describing access method for the requered stream. [scheme:][//][[user:password@]resourcename[?paramters]] |
| AccessMode | |
| StreamHandler | User function that handles stream events |
Returns
none
Example Usage:
static tStreamHnd hRS232=0;
static tStreamHnd hRS485=0;
static tStreamHnd hTCP=0;
static tStreamHnd hGPS=0;
ETIF_StreamClientOpen(&hRS485, "RS485://uart0,9600,8,1,n", 0, StreamEvent_ExternalRS485); // Open an RS485 Stream Client
ETIF_StreamClientOpen(&hRS232, "serial://uart2,115200,8,1,n", 0, StreamEvent_ExternalRS232); // Open a full duplex serial stream
ETIF_StreamClientOpen(&hTCP, "ethernet.tcp://127.0.0.1:8888", 0, StreamEvent_TCP); // Open an Ethernet TCP stream client
ETIF_StreamClientOpen(&hGPS, "cellular.gps://", 0, StreamEvent_GPS); // Subscribe to GPS coordinates
Stream Handler
Example Code for an serial stream handler:
tStreamEventRet StreamEvent_ExternalRS232(tStreamEventHandlerCmd Cmd, s16 (*StreamGetCallBack)(void *Dest))
{
switch(Cmd)
{
case STREAM_DATA_RECEIVE:
{
if( xy_rs232_in_buffer_nb < XY_RS232_INPUT_BUFFER_LENGTH )
{
while( StreamGetCallBack( &xy_rs232_in_buffer[xy_rs232_in_buffer_nb++]) )
{
if( xy_rs232_in_buffer_nb >= XY_RS232_INPUT_BUFFER_LENGTH )
{
break;
}
}
xy_rs232_in_buffer[XY_RS232_INPUT_BUFFER_LENGTH]=0;
ExtRS232InputBufferReadyEvent(ETIF_TIMER_EVENT_SSH, 500);
}
break;
}
case STREAM_OPEN:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("RS232 Stream has opened."));
break;
case STREAM_CLOSED:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("RS232 Stream has closed."));
break;
case STREAM_EMPTY:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("RS232 Stream all data sent."));
break;
default:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("RS232 Stream unhandled/unknown event."));
break;
}
return(0);
/***************************** End of function ********************************/
}
ETIF_StreamClientClose( hStream )
Is used to close a Stream Client when it is not needed any more.
Example Usage:
ETIF_StreamClientClose(&hRS485); // Close Stream Client with handle hRS485
ETIF_StreamClientClose(&hRS232); // Close Stream Client with handle hRS232
ETIF_StreamClientClose(&hTCP); // Close Stream Client with handle hTCP
ETIF_StreamClientClose(&hGPS); // Close Stream Client with handle hGPS
ETIF_StreamClientWrite(hStream, pData, Len )
Is used when application wants to write data to a stream.
Example usage:
c8 Buffer[30];
u8 len = snprintf(Buffer, sizeof(Buffer), "Hello World");
ETIF_StreamClientWrite(&hRS232, Buffer, len);
RTC
To be added
Debug
Serial debug
ETIF_DEBUG_ASC(Level, Message)
Is used for when user wants to output debug string information to the console.
Example Usage:
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("Testing Serial Debug %u", 123 )); // Print string text, formatting as for PRINTF
ETIF_DEBUG_BIN(Level, Message, Len)
Is used for debug binary output in binary hex dump format. Example Usage: ETIF_DEBUG_BIN(ETIF_DEBUG_TRACE, (“”), ExtRS232InputBuffer, NbExtRS232InputBuffer); // Print NbExtRS232InputBuffer bytes binary data of ExtRs232InputBuffer
LED indicators
There are support for three single color LEDs and one bicolor LED on the platform.
These LEDs are used to indicate different operation modes according to the table below.
(Subject to change…)
| LED | COLOR | Description |
|---|---|---|
| D13 | GREEN | LED by the MCU - SystemLED, indicates that the application is running. 1Hz periodic blink @ normal operation, may have different blinking pattern during FW update etc. |
| D11 | BLINKING RED | Device is trying to register to a cellular network |
| D11 | SOLID BLACK (off) | Device have very bad reception |
| D11 | SOLID RED | Device have OK reception |
| D11 | SOLID GREEN | Device have good reception |
| D12 | YELLOW | When off - flashes about every 5 seconds to indicate Device management server connection. When on, to indicate application socket connection it is flashes off about every 5 seconds to indicate dev managment server connection |
| D5 | GREEN | Is handled by the modem, function according to modem documentation. For EHS8/6/5: Slow blinking, about 0.5Hz indicates modem looking for cellular network, short flash every 4th second indicates that the modem has attached to a cellular network |
Input/Output
Low Level Input/Output
Setting up digital I/O
Platform dependent, ask for example project.
SPI
SPI_Init()
Platform dependent, ask for example project.
SPI_Put()
Platform dependent, ask for example project.
SPI_Get()
Platform dependent, ask for example project.
Configuration and non volatile storage
Application compile time configuration
The NCFG Storage system is used for storing parameters to memory that keeps it´s content through a power cycle of the device.
At start up, the stored values are read to a RAM copy.
The application can read values from the RAM copy and write values to the RAM copy.
No changes are saved to the non volatile memory until the command NCFG_SaveToNvm(); is issued.
There are a number of macros to be used for adding different kinds of parameters to the non volatile configuration storage system.
ETIF_AddNvmCfg(ref_name, type, min_value, max_value, default_value)
ETIF_AddNvmCfg_String(ref_name, type, min_size, max_size, default_value)
ETIF_AddNvmCfg_Struct(ref_name, type, default_data)
ETIF_AddNvmCfg_Array(ref_name, type, array_length, default_data )
Parameters that the application wants to store in non volatile memory can be added in a configuration file that is registered to the application in the UEP_ApplConfig.h file of the application.
Example of registration of configuration file in UEP_ApplConfig.h:
_NVM_CONFIG_FILE_ "NvmCfg_ExampleCCD.h"
Example of registration of non volatile storage parameters in configuration file:
Normal numerical parameters:
// Device parameters
NCFG_AddNvmCfg( snr_consec, u32, 0, 0xFFFFFFFF, 0 ) // Holds the serial number of this unit.
NCFG_AddNvmCfg( test_result, u8, 0, 0xFF, 0xFF ) // Indicates the test result from production test
NCFG_AddNvmCfg( prod_test_time, u32, 0, 0xFFFFFFFF, 0 ) // Holds the time of production test
// Application parameters
NCFG_AddNvmCfg( spd_lim_setpoint, u32,30, 120, 50 ) // Holds the speed limiter settings
String parameters:
NCFG_AddNvmCfg_String( string, c8, 1, 30, "Hello Wrld") // String, min size 1 char, max 30 chars, default "Hello Wrld"
Struct parameters:
typedef struct sTestStruct
{
u8 member_1;
u8 member_2;
u8 member_3;
}tTestStruct;
NCFG_AddNvmCfg_Struct( sTest, tTestStruct, {1, 2, 3} ) // Struct of tTestStruct type, default values 1, 2, 3
Array parameters:
NCFG_AddNvmCfg_Array(aTest, u8, 3, {1, 2, 3}) // Array of u8, size 3, default values: 1, 2, 3.
Non volatile ConFiG storage types:
| Type name | Description |
|---|---|
| NCFG_u8 | This is the same as an unsigned char, i.e. 8 bits unsigned value |
| NCFG_u16 | This is the same as an unsigned integer, i.e. 16 bits unsigned value |
| NCFG_u32 | This is the same as an unsigned long, i.e. 32 bits unsigned value |
| NCFG_s8 | This is the same as a signed char, i.e. 8 bits signed value |
| NCFG_s16 | This is the same as a signed char, i.e. 16 bits signed value |
| NCFG_s32 | This is the same as a signed char, i.e. 16 bits signed value |
| NCFG_float | 32 bit float value |
| NCFG_string | Null terminated ASCII string |
| NCFG_struct | The NCFG struct type can contain any type of composite struct type variable |
| NCFG_array | The NCFG_array type is a way to store an array of values of the same type |
NCFG_SaveToNvm()
Is used to save all values that have been changed in the RAM copy to the non volatile memory.
NCFG_GetValue( ref_name )
Is used to fetch the value of a single position numerical value type NCFG parameter from the RAM copy.
Example usage:
u32 speed_limiter_setpoint = 0;
speed_limiter_setpoint = NCFG_GetValue(spd_lim_setpoint); // Fetches the stored value of spd_lim_setpoint to speed_limiter_setpoint variable.
NCFG_GetMaxValue( ref_name )
Is used to fetch the configured max value of a single position numerical value type NCFG parameter from the RAM copy.
Example usage:
u32 speed_limiter_max = 0;
speed_limiter_max = NCFG_GetMaxValue(spd_lim_setpoint); // Fetches the stored value of the max allowed spd_lim_setpoint to speed_limiter_max variable.
NCFG_GetMinValue( ref_name )
Is used to fetch the configured min value of a single position numerical value type NCFG parameter from the RAM copy.
Example usage:
u32 speed_limiter_min = 0;
speed_limiter_min = NCFG_GetMaxValue(spd_lim_setpoint); // Fetches the stored value of the max allowed spd_lim_setpoint to speed_limiter_min variable.
NCFG_GetDefaultValue( ref_name )
Is used to fetch the configured default value of a single position numerical value type NCFG parameter from the RAM copy.
Example usage:
u32 speed_limiter_default = 0;
speed_limiter_default = NCFG_GetMaxValue(spd_lim_setpoint); // Fetches the stored value of the default spd_lim_setpoint to speed_limiter_default variable.
NCFG_SetValue( ref_name, value )
Is used to set a value to the RAM copy of a single position numerical value type NCFG parameter. Example usage:
NCFG_SetValue(spd_lim_setpoint); // Fetches the stored value of the default spd_lim_setpoint to speed_limiter_default variable.
NCFG_GetPointer_String( ref_name )
Is used to get the pointer to the start of a string type NCFG parameter in the RAM copy. Example usage:
c8 address[NCFG_GetMaxSize_String(street_address)]; // Creates array of chars with size of configured maxsize for street_address parameter.
address = NCFG_GetPointer_String(street_address); // Fetches the pointer to start of the street_address string type parameter.
NCFG_GetPointerDefault_String( ref_name )
Is used to get the pointer to the start of the default value of a string type NCFG parameter in the RAM copy. Example usage:
c8 address[NCFG_GetMaxSize_String(street_address)]; // Creates array of chars with size of configured maxsize for street_address parameter.
address = NCFG_GetPointerDefault_String(street_address); // Fetches the pointer to start of default string for the street_address string type parameter.
NCFG_GetMaxSize_String( ref_name )
Is used to get the configured max size of a string type NCFG parameter in the RAM copy. Example usage:
c8 address[NCFG_GetMaxSize_String(street_address)]; // Creates array of chars with size of configured maxsize for street_address parameter.
NCFG_GetMinSize_String( ref_name )
Is used to get the configured min size of a string type NCFG parameter in the RAM copy. Example usage:
u8 min_pwd_size = NCFG_GetMinSize_String(password); // Fetches the minimum length of the password parameter.
NCFG_SetDataString( ref_name, p_src, size )
Is to set data to a string type NCFG parameter in the RAM copy. Example usage:
NCFG_SetData_String(password, "P455w0rd", sizeof("P455w0rd"); // Sets the password parameter to "P455w0rd" in the RAM copy.
NCFG_ClearData_String( ref_name )
Is to clear the data of a string type NCFG parameter in the RAM copy. Example usage:
NCFG_ClearData_String(password); // Clears the password parameter in the RAM copy.
NCFG_GetData_Struct( ref_name )
Is used to fetch the data of a struct type NCFG parameter from the RAM copy.
Application must make sure that data is fetched to the same type as was registered for the parameter when added in UEP_ApplConfig.h
Example usage:
tTestStruct sTestNCFG;
sTestNCFG = NCFG_GetData_Struct(sTest); // Fetches the data of the sTest NCFG parameter to the sTestNCFG struct variable.
NCFG_SetData_Struct( ref_name, struct_data )
Is used to set the data of a struct type NCFG parameter to the RAM copy.
Application must make sure that the that data is put have the same type as was registered for the parameter when added in UEP_ApplConfig.h
Example usage:
tTestStruct sTestNCFG = {4, 5, 6};
NCFG_GetData_Struct(sTest, sTestNCFG); // Sets the data of the sTestNCFG struct to the sTest NCFG parameter.
NCFG_ClearData_Array( ref_name )
Is used to clear the entire array for a array type NCFG parameter in the RAM copy.
Example usage:
NCFG_ClearData_Array(aTest); // Clears the data of the aTest array type NCFG parameter in the RAM copy.
NCFG_SetData_Array( ref_name, index, data )
Is used to set one position of an array type NCFG parameter in the RAM copy.
Example usage:
NCFG_SetData_Array(aTest, 3, 34); // Sets the value "34" to position 3 of aTest array type NCFG parameter in the RAM copy.
NCFG_GetData_Array( ref_name, index )
Is used to get the data of one position of an array type NCFG parameter from the RAM copy.
Example usage:
u8 array_pos_3;
array_pos_3 = NCFG_GetData_Array(aTest, 3); // Gets the value that is stored in position 3 of aTest array type NCFG parameter in the RAM copy.
Miscellaneous
ETIF_FLAGS
Flags are used to mark different events in the system and are available for the entire application. Flags are different from setting up global boolean variables in the way that the flags are stored in a very compressed way in a bitfield.
Currently the application programmer may not add own flags.
Existing flags are found in ETIF_Registry.h
ETIF_FLAG_CHK()
Is used to check the status of a flag.
Example usage:
if( ETIF_FLAG_CHK(FIRMWARE_DOWNLOAD) )
{
while(ETIF_FLAG_CHK( FIRMWARE_DOWNLOAD )
{ // Fast blink with LED while FW download in progress.
mSysLED_Toggle();
ETIF_THREAD_DELAY(250);
}
}
ETIF_FLAG_SET()
Is used to change the status of a flag to TRUE.
Example usage:
ETIF_FLAG_SET(MY_FLAG);
ETIF_FLAG_CLR()
Is used to change the status of a flag to FALSE.
Example usage:
ETIF_FLAG_CLR(MY_FLAG);
SIM and Cellular properties.
Connected to the SIM card the Cellular module and the mobile network cell that the device is connected to is a number of properties that may be interesting for the application.
SIM Properties
| Property | Description |
|---|---|
| ICCID | This is the Integrated Circuit Card IDentifier number |
| IMSI | This is the International Mobile Subscriber Identity |
| RSSI | This is the Received Signal Strength Indicator |
In order to extract this information, the example code below may be used.
u8 ETIF_CellularSignalRSSI(void);
c8 *ETIF_CellularSIMICC(void);
c8 * ETIF_CellularSIMIMSI(void);
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("RSSI = %u", (unsigned int)ETIF_CellularSignalRSSI()));
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("ICCID = %s", ETIF_CellularSIMICC() ));
Cellular module properties
| Property | Description |
|---|---|
| IMEI | This is the International Mobile Equipment Identity number |
In order to extract this information, the example code below may be used.
c8 *ETIF_CellularIMEI(void);
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("IMEI = %s", ETIF_CellularIMEI() ));
Mobile network cell properties
| Property | Description |
|---|---|
| Type | This is the network type, for most modules it can be “3” for “3G” or “2” for 2G |
| MCC | This is the Mobile Counry Code |
| MNC | This is the Mobile Network Code |
| LAC | This is the Location Area Code |
| LCID | This is the Long Cell ID - a concatenation of the RNC-ID (12 bits, ID of the Radio Network Controller) and Cell ID (16 bits, unique ID of the Cell) |
| CID | This is the 16 bit unique Cell ID, can be extracted from LCID by masking out 16 least significant bits |
In order to extract this information, the example code below may be used. Make sure variables are static, otherwise the framework will reuse the memory space and the output will be erratic.
{
static u8 network_type;
static u32 network_mcc, network_mnc, network_lac, network_cid, network_lcid;
while(!network_type)
{
CellDrv_CellInfo(&network_type, &network_mcc, &network_mnc, &network_lac, &network_lcid);
network_cid = network_lcid & 0x000FFFF;
ETIF_THREAD_DELAY(500);
}
ETIF_DEBUG_ASC(ETIF_DEBUG_TRACE, ("Type: %u, MCC: %u, MNC: %u, LAC: %u, CID: %u, LCID: %u", network_type, network_mcc, network_mnc, network_lac, network_cid, network_lcid));
// If application wants to send info to server, make sure that the resources below are registered in the ETIF_AppRegistry.h file
ETIF_ResourcePut( DEFAULT, ccd_network_type, &network_type );
ETIF_ResourcePut( DEFAULT, ccd_network_mcc, &network_mcc );
ETIF_ResourcePut( DEFAULT, ccd_network_mnc, &network_mnc );
ETIF_ResourcePut( DEFAULT, ccd_network_lac, &network_lac );
ETIF_ResourcePut( DEFAULT, ccd_network_lcid, &network_lcid );
ETIF_ResourcePut( DEFAULT, ccd_network_cid, &network_cid );
}