Gemalto is now part of the Thales Group, find out more.

You are here

Thales IoT Developer Community

How to update module firmware with Module Services

Tutorial, April 12, 2018 - 4:53pm, 5660 views


This tutorial shows how to update the module’s firmware. The same procedure also applies for Module Services Agent update.


Preconditions for firmware update

As a precondition, you need to be registered to Module Services. Please see this link for more details:

The module ***** to be provisioned to Cinterion Module Services and The Service Agent ***** to be activated on each module. Please see this link for information how to do it:


Device selection process

As each wireless module provisioned to Module Services ***** to have IMEI number assigned, the easiest way to find the device is to search by its IMEI. It can be pasted to the "Search IMEI" field at the top of the page. Then the "Devices" tab will open and the searched device will be displayed.



Another way is to open "Devices" tab and use the provided filters. Modules can be searched by IMEI, organization, group, type, firmware revision and many others. 

An interesting option is to the possibility to display all devices that can be updated to a certain firmware version, i.e. all the devices that currenlt have lower firmware version installed and can be safely updated to the selected one. It can be done by choosing 'Eligible firmware revision' filter, selecting the desired firmware version from the drop-down list and clicking 'OK'.


Eligible devices


Then there is a possibility to select all or only some of the found modules.

To search by group there must be a group created first. To do that, the list of devices should be displayed, there may be some filters applied to display the targeted devices. Then, each device that is intended to be added to the group must be selected (there are checkboxes on the right). After that, 'Take an action' should be clicked and 'Create Group' chosen from the list. 

search 2


The last step is to specify the name and click "OK".


Firmware update task programming, execution and follow-up (1 device)

Search for module and select it in the same way as for creating a group. Then click “Take an action” and this time choose “Firmware Update”. The following screen will be displayed:

FOTA form


Enter a label that will be as a unique identifier of the task, choose the firmware version from the list (in case of selecting modules by  'Eligible firmware revision'  it is already set), and configure start date and timeout.

If the task is not successfully executed before its timeout, it will be finished with the error code “Expired”. While configuring the timeout, please take into consideration the module’s connection rate (the minimum allowed connection interval is 4 hours) – more than one connection may be needed to complete the process.

After the task has been created the results may be traced on the “Tasks” tab:

FOTA task started


After it’s finished the status changes to "Completed":

FOTA task finished


To see the execution status, click the circle graph on the “Execution Status” area. The following screen will appear:

FOTA status


For more details click the magnifier icon on the right. Each step can be expanded like below:

FOTA execution details


To see the task details click the “…” on “Task details” area:

FOTA details


In newer Service Agent versions there are URC’s with status displayed by the module during download:

^SRVACT: "SLAE","download-progress",32,0

^SRVACT: "SLAE","download-progress",73,0

^SRVACT: "SLAE","download-progress",100,0

Please refer to your Cinterion module’s documentation for details on these URC’s.


How to execute the same task on multiple devices

Firmware update task (as any other task) can be scheduled for execution on more than one device at once. The procedure is exactly the same as for one device. Just more devices should be selected form the list before starting the “Firmware Update” task. Device groups may be helpful here. Devices of the same type should only be chosen for such task so that the selected firmware file would match for all of them. In other case there will be an error during the task creation.

When the task is created it can be traced on the “Tasks” tab. The execution status will then show the status and details for each module separately.


Error handling and troubleshooting

In case of failure the task is marked with “err” on the tasks list, and also there is black color on “Execution Status” and “Task progress” graphs. The detailed status can be seen in the same way as before. 

Example status:

FOTA error


Example details:

FOTA error 1


In such case there is also a possibility to retry the task without a need to create it again. To do this just open “Task Execution Status”, choose the device or devices for which the update task was not successful and just click “Retry”.

FOTA retry


Then the task start date and timeout need to be set and that’s it. 

FOTA retry task


Now just wait for results.


Bartłomiej Gemalto Moderator's picture
Bartłomiej Gemalto Moderator