Everyware™ Software Framework
PART 3. ESF CODE EXAMPLES
Update Manager Service
· Overview
· Update Manager Service Example
Example
Overview
This example shows how to use the Update Manager Service
as well as create an update to update a device.
The ESF Update Manager Service uses the ESF Configuration Manager (CM)
to get software updates into ESF. The CM
is already highly adaptable in terms of getting Objects from remote locations
into specific bundles. So, the Update
Manager Service uses this as the mechanism to get the updates into the
system. This is described in more detail
here. The CM is described in more detail here and a code example is here.
In this example you will learn how to:
- Create
an update that can deployed on a working system
- Deploy
the created update to a target system
Prerequisites
- Installing the Eclipse
IDE
- Integrating ESF Tooling and Projects
into Eclipse
- Using Working Sets
- Hello World Using the ESF Logger
- Configuration Manager Service
Update Manager Service Example
This howto goes through the process of creating an update
to deploy to a target system. This
involves creating a zip file with a ‘version_multi.txt’ and one or more ‘star’
files in it. The update service is
capable of deploying a series of updates.
The reason for this is in part to keep updates small as well as to allow
updates to be incremental as old units may come online. Regardless, this structure does not prevent
monolithic non incremental updates. One
could create separate updates where each update included all of the previous
updates as well. Then when deploying the
updates the zip file contains a version_multi.txt that only refers to a single
star file that is the combination of all previous updates.
In this example we are going to make a very simple update. We are going to add a single bundle and
update the /etc/esf/*release*.txt file to reflect the new version. By default every unit should have a
/etc/esf/*release*.xml file. The format
for this name is BOARD_PRODUCT_NAME_release-MAJOR.MINOR.SUBMINOR.xml. In this example we are using a Helios and the
product is called Tomahawk. The current
release of tomahawk is 1.0.0. So the
release file is /etc/esf/helios_tomahawk_release-1.0.0.xml. In this update we are going to add a new
business logic bundle (the hello world bundle from Hello World Using the ESF
Logger), a modified services.xml file to automatically start the bundle, and a
new release.xml file to reflect the changes.
In order to do this, we need the star builder
components. There are four files of
importance. There is the
‘makeEsfStar.sh’ which is the script that is run to generate the actual star
file. It has four parameters that must
be set on a project by project basis.
These are:
COMPANY=[the company that owns the product]
PROJECT=[the product name – tomahawk in our example]
UPDATE_SERVER_LOCATION=[URL of the update server if one
exists (can be blank)]
UPDATE_SERVER_FILE=[the name of the version_multi.txt]
These are the example parameters
COMPANY=Eurotech
PROJECT=tomahawk
UPDATE_SERVER_LOCATION=
UPDATE_SERVER_FILE=version_multi.txt
If the UPDATE_SERVER_LOCATION is set the makeEsfStar.sh
script will fetch the UPDATE_SERVER_FILE from the server and append the new
line to it. If it is not specified it
simply creates a new version_multi.txt that only contains one line representing
the new star file being created.
The second piece of interest in the making of star files
is the file called fileIncludeList. This
is simply a list of files with their full paths that should be included in the star
file. This is the fileIncludeList for
our example.
# Include below a list of all the filesystem files to be
included
# excluding all the Debians (.deb), and typically
excluding the .jar files
/etc/esf/helios_tomahawk_release-1.0.0.xml
/opt/jvm/esf/bundlefiles/com.esf.example.helloworld_1.0.0.201007301252.jar
/opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml
There are two additional files that are of interest in
the star file creation. These are the
preinst_script and the postinst_script.
As the names suggest these are scripts that are put into the star file
and run either before or after the main tar file containing the files in
fileIncludeList is extracted. These can
be used to do work like deleting old files, logging information, or installing
RPMs. These are the examples for this
howto.
root@localhost:/tmp>
cat preinst_script
#!/bin/sh
date
>> /tmp/update.txt
echo
preinstall script in update 1.0.0 was run >> /tmp/update.txt
echo
removing old helios_tomahawk_release-1.0.0.xml >> /tmp/update.txt
rm
/etc/esf/helios_tomahawk_release-1.0.0.xml
root@localhost:/tmp>
cat postinst_script
#!/bin/sh
date
>> /tmp/update.txt
echo
postinstall script in update 1.0.0 was run >> /tmp/update.txt
So, with these files now set in place we can run the
makeEsfStar.sh to build the update. All
four of these files (makeEsfStar.sh, fileIncludeList, preinst_script, and
postinst_script) should be placed in /tmp/ on the target. This target must have manually been modified
with all of the changes going into the update.
The makeEsfStar.sh script pulls the files in the fileIncludeList from
this unit. Once that is done we can
simply run the update. This is the
output for our example.
#######################################################################################
root@localhost:/tmp>
./makeEsfStar.sh
making
/tmp/new_star
validating
versions
the current
version is: 1.1.0
fetching the
latest releases.txt file
not making
/tmp/ dir
Tarring the
following files into the star file...
./
./opt/
./opt/jvm/
./opt/jvm/esf/
./opt/jvm/esf/configuration/
./opt/jvm/esf/configuration/.esf/
./opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/
./opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml
./opt/jvm/esf/bundlefiles/
./opt/jvm/esf/bundlefiles/com.esf.example.helloworld_1.0.0.201007301252.jar
./etc/
./etc/esf/
./etc/esf/helios_tomahawk_release-1.1.0.xml
./tmp/
./tmp/postinst_script
./tmp/preinst_script
Adding .star
pre-script /tmp/preinst_script.
Adding .star
post-script /tmp/postinst_script.
removed
`/tmp/new_star/opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml'
removed
directory:
`/tmp/new_star/opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap'
removed directory:
`/tmp/new_star/opt/jvm/esf/configuration/.esf'
removed
directory: `/tmp/new_star/opt/jvm/esf/configuration'
removed
`/tmp/new_star/opt/jvm/esf/bundlefiles/com.esf.example.helloworld_1.0.0.201007301252.jar'
removed
directory: `/tmp/new_star/opt/jvm/esf/bundlefiles'
removed
directory: `/tmp/new_star/opt/jvm/esf'
removed
directory: `/tmp/new_star/opt/jvm'
removed
directory: `/tmp/new_star/opt'
removed
`/tmp/new_star/etc/esf/helios_tomahawk_release-1.1.0.xml'
removed
directory: `/tmp/new_star/etc/esf'
removed
directory: `/tmp/new_star/etc'
removed
`/tmp/new_star/tmp/postinst_script'
removed
`/tmp/new_star/tmp/preinst_script'
removed
directory: `/tmp/new_star/tmp'
removed
directory: `/tmp/new_star'
adding: eurotech_tomahawk_update-1.1.0.star
(deflated 17%)
adding: version_multi.txt (deflated 6%)
com_esf_core_updater.file
eurotech_tomahawk_update-1.1.0.star
created successfully:
star file is
/tmp/eurotech_tomahawk_update-1.1.0.star
version
multi is /tmp/version_multi.txt
update file
is /tmp/tcd_file_tgz_1.tgz
#######################################################################################
This now gives us three new files in /tmp/. These are tcd_file_tgz_1.tgz,
eurotech_tomahawk_update-1.1.0.star, and version_multi.txt. These can now be placed on an update server
or deployed directly to other targets.
The tcd_file_tgz_1.tgz file can be used to apply the update via the CM
HTTP service. This can be opened with a
browser at http://[ip_address]/com/esf/core/configuration/cpi/HttpServer. This will open a simple dialog as shown in
figure 1.
Figure 1 Uploading the
Update
Browse to the tcd_file_tgz_1.tgz file you have copied
over to your PC. Then simply click the Upload
button. On the ESF console you should
see the following output.
[WARNING]
2010-07-30 22:05:36.944 - com.esf.core.updater.EsfUpdater:
******************************** WARNING
- ABOUT TO UPDATE
********************************
[WARNING]
2010-07-30 22:05:36.945 - com.esf.core.updater.EsfUpdater: about to update from
1.0.0 to 1.1.0
[WARNING]
2010-07-30 22:05:36.945 - com.esf.core.updater.EsfUpdater: ESF will shut down
for the udpate and the unit may reboot depending on what the update includes
[WARNING]
2010-07-30 22:05:36.945 - com.esf.core.updater.EsfUpdater: Do not remove power
to the unit until this process is complete
[WARNING]
2010-07-30 22:05:36.946 - com.esf.core.updater.EsfUpdater:
******************************** WARNING
- ABOUT TO UPDATE ********************************
[WARNING]
2010-07-30 22:05:37.129 - com.esf.core.updater.EsfUpdater:
******************************** END
WARNING – UPDATE COMPLETE!
********************************
The code to create this update can be found here. This does not need to be imported into
Eclipse as it all runs on the target system.
Copyright © 2010 Eurotech Inc. All rights reserved.