UM1610
SPC5Studio components writers guide
Introduction
Figure 1: SPC5Studio - Copyrights STMicroelectronics (c) 2014
SPC5Studio provides mechanisms that can be used to design, build and deploy embedded applications
components for the SPC5 Application Configuration Editor.
July 2014
DocID024250 Rev 3
1/38
www.st.com
Contents
UM1610
Contents
1
2
Components .................................................................................... 4
1.1
Definition ........................................................................................... 4
1.2
Structure ........................................................................................... 4
1.3
Dependencies ................................................................................... 6
1.4
Features ............................................................................................ 6
Creating a new Component project ............................................... 8
2.1
Configuring the plugin.xml ............................................................... 11
2.2
Adding files to the component ......................................................... 12
2.3
Defining the component data model................................................ 12
2.4
2.3.1
The extension tree ............................................................................ 12
2.3.2
The extension tree elements (version V0)........................................ 15
2.3.3
The extension tree elements (version V1)........................................ 19
2.3.4
Importance of descriptions ............................................................... 28
2.3.5
Wizards ............................................................................................. 29
Writing templates ............................................................................ 30
2.4.1
FTL in brief ....................................................................................... 30
2.4.2
The SPC5 data model namespaces ................................................. 31
2.4.3
Examples .......................................................................................... 32
2.5
Testing a component ....................................................................... 32
2.6
Deploying a component .................................................................. 33
3
Development references ............................................................... 36
4
Revision history ............................................................................ 37
2/38
DocID024250 Rev 3
UM1610
List of figures
List of figures
Figure 1: SPC5Studio - Copyrights STMicroelectronics (c) 2014 .............................................................. 1
Figure 2: Project explorer ........................................................................................................................... 5
Figure 3: Dependencies .............................................................................................................................. 6
Figure 4: Component wizard ....................................................................................................................... 8
Figure 5: SPC5 component project general page ...................................................................................... 9
Figure 6: SPC5 Studio details page .......................................................................................................... 10
Figure 7: Component features .................................................................................................................. 11
Figure 8: Overview .................................................................................................................................... 12
Figure 9: Plugin.xml extension tab ............................................................................................................ 13
Figure 10: Testing a component ............................................................................................................... 14
Figure 11: Deploying a component ........................................................................................................... 15
Figure 12: Component properties ............................................................................................................. 16
Figure 13: Groups definition properties .................................................................................................... 17
Figure 14: Group definition properties ...................................................................................................... 17
Figure 15: Property definition properties ................................................................................................... 18
Figure 16: Description element properties ................................................................................................ 19
Figure 17: Description element group ....................................................................................................... 21
Figure 18: Description element details ..................................................................................................... 22
Figure 19: Description element metadata temperature units.................................................................... 25
Figure 20: Description element metadata distance units .......................................................................... 25
Figure 21: Description element metadata other units ............................................................................... 26
Figure 22: Description element metadata other units overview ............................................................... 26
Figure 23: XPath expressions ................................................................................................................... 27
Figure 24: XPath expressions view .......................................................................................................... 28
Figure 25: XPath expressions results ....................................................................................................... 28
Figure 26: Description element ................................................................................................................. 29
Figure 27: Components wizard ................................................................................................................. 30
Figure 28: Eclipse launch configuration .................................................................................................... 33
Figure 29: Overview .................................................................................................................................. 33
Figure 30: Project explorer context menu ................................................................................................. 34
Figure 31: Export menu ............................................................................................................................ 35
DocID024250 Rev 3
3/38
Components
1
UM1610
Components
Each SPC5 component can be defined, tested and deployed through Eclipse PDE
framework.
An SPC5 component corresponds to an Eclipse plugin and, as such, it can be built and
managed using Eclipse PDE.
The following pages describe the most important SPC5 Components aspects.
1.1
Definition
An SP5 Component is the main part of an SPC5 Application. As in a layered architecture, a
component offers services to other components and also use their services.
It essentially consists of C Source libraries (both source code and compiled libraries),
configuration files, C source code and header templates.
All these files are arranged in a defined directory hierarchy, which are used by SPC5Studio
in order to generate the application source code.
A component may also depends on other components: this dependency is managed by
Eclipse PDE / OSGi framework.
We can distinguish two types of components:
1.2
Platform components: represents the root component of an application. It defines
the main services of the target platform used in the embedded application.
Non-Platform components: represents all other kind of components. A non-platform
component, for example, may offer services like RTOS libraries, IO, ... .
Structure
An SPC5 component contains the following file structure:
4/38
DocID024250 Rev 3
UM1610
Components
Figure 2: Project explorer
Where:
Java classpath: contains all the Java/PDE files used by Eclipse PDE
Java source folder: contains the class activating the Eclipse plugin and optionally an
implementation of ISPC5ComponentProcess interface that provides method used
used during the application generation.
ISPC5ComponentProcess interface implements the following methods: preProcess: a
method called during application generation, before parsing the current
component;postProcess: a method called during application generation, after current
component has been parsed;init: a method called before the component has been
added to the application tree. You can use this method to show license information
using UI objects.
Component folder structure
cfg: contains component source/configuration/templates file copied during
application generation;
doc: contains component documentation that is copied into the application folder
structure;
lib: contains components source code or library code that need to be used in the
application generation. The content of this folder is copied or linked according to
the application type (i.e.: standalone or not);
mak: contains component make files or their templates;
root_wa: contains files that are copied in the application root folder on every
application generation;
root_wo: contains files that are copied in the application root folder only once.
Eclipse PDE files: used to build and deploy the plugin constituting the component.
DocID024250 Rev 3
5/38
Components
UM1610
An optional presets folder can be added: the SPC5 configurator use this folder in order
to search for component instances presets.
An optional ftllibs folder can be added: this contains the FreeMarker libraries used by
the component Freemarker templates.
1.3
Dependencies
An SPC5 component may depend on other Eclipse/SPC5 Components. In order to add
such dependencies, simply click on the Add button of the plugin.xml dependencies tab and
a list of alla available plugins (including SPC5 components) is shown.
After adding the component you can manage dependent component version, selecting the
Properties... button.
Figure 3: Dependencies
1.4
Features
Each component and the application node contain a set of exported and imported features.
These features represent the identification of a certain constraint that the application has to
satisfy. There are two main kinds of features:
See Section 2.3: "Defining the component data model" for a more detailed description of
how to define a feature.
Exported Features
Represent the feature that the component or the application is able to satisfy. Exported
Features can also be
6/38
DocID024250 Rev 3
UM1610
Components
Exclusive: the feature can be required only once.
Non-Exclusive: the feature can be required more than once.
Required Features
Represent a required feature that needs to be present in order to successfully generate or
build the application.
In general, features are defined and implemented in the belonging component. You can
also define one or more new features in the application, using the controls below the
feature table.
DocID024250 Rev 3
7/38
Creating a new Component project
2
UM1610
Creating a new Component project
SCP5Studio provides a wizard used to create a new component.
These chapters guide the user through the process of creating, defining, testing and
deploying an SPC5 Component.
Figure 4: Component wizard
Using SPC5 Component wizard, you are prompted to enter the project name:
8/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 5: SPC5 component project general page
For better debugging the component, DO NOT use spaces in project name.
Then you enter different information needed to build the component:
DocID024250 Rev 3
9/38
Creating a new Component project
UM1610
Figure 6: SPC5 Studio details page
Component name: is a user readable name that identifies the component;
Component ID: is the unique identifier of the component: a java package style is used
to define IDs;
Component description: a description of your plugin;
Processing interface: the ISPC5ComponentProcess interface implementation (see
Section 1.2: "Structure")
Platform Plugin: a flag indicating whether the component is a platform component or
not (see Section 1.1: "Definition")
Hidden: a flag indicating whether the component shall be hidden in the Add dialog of
SPC5Studio Application configuration.
In the following pages you define component features (see Section 1.4: "Features"). You
can also click finish and enter them later.
10/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 7: Component features
A plugin project is created in the workspace (see Section 1.2: "Structure")
2.1
Configuring the plugin.xml
In order to configure the component, you need to use the plugin configuration features
provided by Eclipse PDE. The plugin configuration can be done by entering some
configuration parameters in the plugin.xml file as shown in the following figure:
DocID024250 Rev 3
11/38
Creating a new Component project
UM1610
Figure 8: Overview
Using the editor bottom tabs, you enter all the parameters of your component.
2.2
Adding files to the component
You can add various kind of files to your component, according to the component structure
(see Section 1.2: "Structure").
The file component.mak
The component make file contains the component compiler/linker settings used to build the
component itself. This file could also be a template, configured with the properties defined
in the component extension point and component datamodel (see Section 2.3: "Defining
the component data model" and Section 2.3.1: "The extension tree").
2.3
Defining the component data model
The component needs a data model in order to let SPC5Studio generate the application
from the component templates. This data model contains two main parts:
User properties definition
Global properties
See the following topics.
2.3.1
The extension tree
The user data model can me defined using the plugin.xml extension tab. Through the
Eclipse extension mechanism, this data model is provided to SPC5Studio.
12/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 9: Plugin.xml extension tab
The Eclipse plugin.xml editor provides a user friendly interface that guides the user in
compiling the extension. Just right-click on the selected element and a menu guides you
through inserting the correct element of the datamodel. On the right side of the editor, the
current selection elements are shown.
SPC5Studio supports different extension version upon which you can build your
components.
Each element also has a description associated as tooltip.
Moreover, you can read the documentation of the Extension Point schema and its DTD:
right click on the extension point element and the following element appears:
DocID024250 Rev 3
13/38
Creating a new Component project
UM1610
Figure 10: Testing a component
Clicking on Show Description, the following html page describing the extension point
schema appears:
14/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 11: Deploying a component
The SPC5 Extension contains the following attributes:
point: the SPC5 extension point.
id: the SPC5 component ID.
name: the SPC5 component name.
The elements have the following children:
2.3.2
process: apply init, pre and post process while generating SPC5 application from this
component. The class element contains the Java class implementing
ISPC5ComponentProcess interface;
component: see Section 2.3.1: "The extension tree" .
The extension tree elements (version V0)
Component
The first element to configure is the Component element.
DocID024250 Rev 3
15/38
Creating a new Component project
UM1610
Figure 12: Component properties
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions";
groups: see the following section;
requiredFeatures: contains a list of features required by this component: the attribute
id contains the unique feature identifier for the required feature
exportedFeatures: contains a list of features that this component shall export. Each
element contains the following attributes:
id: the feature unique identifier.
brief: the feature brief description.
exclusive: true if this feature is exclusive
The SPC5 component contains the following attributes:
icon: the component icon file.
isPlatform: true if this component implements a platform specific component.
headerName: the C-Symbol name of the component main header file.
initFunction: the C-Symbol name of the component initialization function.
hidden: if true, the add dialog does not show this component by default.
Groups
A Groups element is the container of all the properties groups.
16/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 13: Groups definition properties
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions";
group: a list of groups, see the following section;
The SPC5 groups contain the following attributes:
name: the group name.
Group
A Group element is the container of all the properties. It is rendered as an expandable
widget: so you can define to expand this container by default or not.
Figure 14: Group definition properties
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions"
property: a list of properties, see the following section
The SPC5 group contains the following attributes:
name: the group name
expanded: if true this group is always expanded
DocID024250 Rev 3
17/38
Creating a new Component project
UM1610
Properties
The Property element is the core of the data model. It represents the container of the data
and its constraints that SPC5Studio uses to render the user interface and to generate the
code from all the templates.
Figure 15: Property definition properties
This element has the following child:
groups: the groups property is used when property is of type list. In this case, the list
elements definition is provided to SPC5Studio through this groups definition.
The SPC5 property contains the following attributes:
18/38
type: the property type. For "list" property type, you need to populate the "groups"
child. Note: for "formatted" property type, its content is added as a CDATA node in the
data model. Property type is one of the following values:
boolean: a boolean property rendered as a checkbox
enum: an enumarative type rendered as a combo box
float: a floating point number rendered as a text field with numeric validation
signed: a signed integer number written as hex or base 10 decimal rendered as a
text field with numeric validation
unsigned: an unsigned integer number written as hex or base 10 decimal
rendered as a text field with numeric validation
DocID024250 Rev 3
UM1610
Creating a new Component project
2.3.3
string: a string field rendered as text field
text: a multiline text field
formatted: a multiline formatted text field (it can be used to enter code snippets)
list: an array of elements, previewed as a table. Each table element is rendered
like a Groups elements.
brief: the property tooltip to display.
name: the property name. No duplicats admitted within a group.
default: for HEX property type this value is a valid hexadecimal value. For Enum
property type, this value is the enum selection index. For List, Text, Formatted
property type, this value is the height of the control in pixel.
value: use comma separated values. This field is used for enum property type. It is
also used for List property type: each comma separated value is in the form
groupName|propertyName[column size]. It represents a column to show in the table.
length: the property length. For List property type, this value is the default number of
rows.
regex: a regex to match for property validatation.
editable: true to let the SPC5 application configurator enable editing on such fields.
required: true if the property value is required.
min: the minimum value accepted for this field (integer only). For List property type,
this value is the minimum number of rows.
max: the maximum value accepted for this field (integer only). For List property type,
this value is the maximum number of rows.
The extension tree elements (version V1)
Component
The first element to configure is the Component element.
Figure 16: Description element properties
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions";
categories: see the following section;
configuration: see the following section;
DocID024250 Rev 3
19/38
Creating a new Component project
UM1610
requiredFeatures: contains a list of features required by this component: the attribute
id contains the unique feature identifier for the required feature
exportedFeatures: contains a list of features that this component shall export. Each
element contains the following attributes:
id: the feature unique identifier
brief: the feature brief description
exclusive: true if this feature is exclusive
The SPC5 component contains the following attributes:
icon: the component icon file.
isPlatform: true if this component implements a platform specific component.
headerName: the C-Symbol name of the component main header file.
initFunction: the C-Symbol name of the component initialization function.
hidden: if true, the add dialog does not show this component by default.
Categories
A categories element is the container of all the categories in which you want to classify the
component.
A category is used in the "add dialog" of the UI of the SPC5 configuration editor.
This element has the following child:
category: the id of a category you want to use. You can define a category using also
one or more path elements separated by "/". (e.g.: "com/st/tools/spc5/category")
Configuration
A configuration element is the container of all the properties and groups.
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions";
property: a list of properties, see the following section;
group: a list of groups with their own styles;
image: an image and an optional description (see Section 2.3.4: "Importance of
descriptions");
line: a separator line;
text: a description text (see Section 2.3.4: "Importance of descriptions");
Group
A Group element is the container of all the properties. It is rendered as an expandable
widget, a button or a link: so you can define to expand this container by default or not.
It supports also arrangement of the children properties in one or more columns through the
"column" attribute.
The style attribute can be used in order to change the group appearance:
20/38
collapsable: is the default style. It renders the group as a collapsable element.
link: it renders the group as a link. You need to click in order to enter the group.
button: it renders the group as a button. You need to click in order to enter the group.
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 17: Description element group
This element has the following children:
description: see Section 2.3.4: "Importance of descriptions";
property: a list of properties, see the following section;
group: a list of groups with their own styles;
image: an image and an optional description (see Section 2.3.4: "Importance of
descriptions");
line: a separator line. It supports the hidden attributes: if hidden attribute is set to true,
the line tag will be used as a breaking element, without rendering any widget.
text: a description text. Add a text in a group between properties. Use HTML tag <br>
or <br/> to make a new line. It also is used to describe a property. This information will
be displayed in the Property View on widget label click.
The SPC5 group contains the following attributes:
name: the group name.
expanded: if true this group is always expanded.
style: the style of the group.
columns: the number of columns of the group. When using the common navigator
you can add a "*" after the number in order to multiply by 2 the column number if the
common navigator has been enabled.
wizard: the extension id implementing 'com.st.tools.spc5.wizard' extension. (see
Section 2.3.5: "Wizards" )
Properties
The Property element is the core of the data model. It represents the container of the data
and its constraints that SPC5Studio uses to render the user interface and to generate the
code from all the templates.
DocID024250 Rev 3
21/38
Creating a new Component project
UM1610
Figure 18: Description element details
This element has the following child:
group: the group property is used when property is of type list : in this case, the list
elements definition will be provided to SPC5Studio through this groups definition.
override: used to override properties attributes when enabling/disabling or validating
property content. Different criteria may be applied.
It support the following attributes (i.e. attribute of the property field that can be
overridden).
editable: if this field contains a feature id (prefixed by '@'), than the property will
be enabled according to the existence of the given feature. If the field starts with
test: then the property will be enabled according to the xpath evaluation result.
Note: Supports XPath 1.0. It will be evaluated from current node. An XPath shall
contain the properties names as specified in the configuration.xml file.
valid: this field contains an XPath that will be verified for property validity. The
field shall be prefixed with test:.
Note: Supports XPath 1.0. It will be evaluated from current node. An XPath shall
contain the properties names as specified in the configuration.xml file.
invalid_message: the message that will be displayed when the 'valid' xpath has
not been satisfied.
default: this field contains an xpath expression that will be evaluated in order to
fill the default property value (according to the property type). The field shall be
prefixed with xpath:.
Note: Supports XPath 1.0. It will be evaluated from current node. An XPath shall
contain the properties names as specified in the configuration.xml file.
text: a description text. Add a text in a group between properties. Use HTML tag <br>
or <br/> to make a new line. It also is used to describe a property. This information will
be displayed in the Property View on widget label click.
The SPC5 property contains the following attributes:
22/38
DocID024250 Rev 3
UM1610
Creating a new Component project
type: the property type. For "list" property type, you need to populate the "group" child.
Note: for "formatted" property type, its content is added as a CDATA node in the data
model. Property type is one of the following values:
boolean: a boolean property rendered as a checkbox;
enum: an enumarative type, it will be rendered as a combo box;
float: a floating point number be rendered as a text field with numeric validation;
signed: a signed integer number written as hex or base 10 decimal rendered as a
text field with numeric validation;
unsigned: an unsigned integer number written as hex or base 10 decimal
rendered as a text field with numeric validation;
string: a string field rendered as text field;
text: a multiline text field;
formatted: a multiline formatted text field (it can be used to enter code snippets);
list: an array of elements, previewed as a table. Each table element is rendered
like a Group element.
brief: the property tooltip to display.
name: the property name. No duplicats admitted within a group.
default: for HEX property type, this value is a valid hexadecimal value. For Enum
property type, this value is the enum selection index. For List, Text, Formatted
property type, this value is the height of the control in pixels.
value: use comma separated values. This field is used for enum property type. It is
also used for List property type: each comma separated value is in the form
groupName|propertyName[column size]. It represents a column to show in the table.
length: the property length. For List property type, this value is the default number of
rows. For Unsigned properties this value is the step of the valid value.
regex: a regex to match for property validatation.
editable: true to let the SPC5 application configurator enable editing on such fields,
false otherwise. You can enter a feature id prefixed by "@", in order to enable the
property only if the feature is available (e.g.: "editable="@feature.id").
required: true if the property value is required.
min: the minimum value accepted for this field (integer only). For List property type,
this value is the minimum number of rows.
max: the maximum value accepted for this field (integer only). For List property type,
this value is the maximum number of rows.
style: use style flag in order to customize unsigned and enum properties.
text: text field style for unsigned properties (default)
slider: slider style for unsigned properties (max and min required)
spinner: spinner style for unsigned properties (max and min required)
scale: scale style for unsigned properties (max and min required)
radio: radio style for enum properties
combo: combo style for enum properties (default)
list: list style for enum properties
Properties metadata
Properties may be affected a list of metadata. A metadata is defined by:
a
name
(a)
value
class
Metadata represents any kind of named information a component writer may want to add to
a component's property.
a
Name and value attributes are mandatory, while class attribute is optional.
DocID024250 Rev 3
23/38
Creating a new Component project
UM1610
The class assigned to a metadata allows for handling the metadata object using a specific
interface: IMetadataHandler, which is defined as is:
public interface IMetaDataHandler {
/**
* Handle an action requested on a metadata
*
* @param metadata
*
the metadata reference
* @param source
*
the source of the object calling the handle
* @param actionName
*
the name of the action to be taken
* @param args
*
arguments to be passed to the action
* @return an object representing the result of the handle operation
*/
public Object handle(PropertyMetadata metadata, Object source,
String actionName, Object... args);
/**
* Generate a property: i.e. return a DOM Element to be saved to the
* configuration file
*
* @param metadata
*
the metadata reference
* @param property
*
the property to be saved
* @return the DOM element created with attributes and values from the
given
*
property
*/
public Element generateProperty(PropertyMetadata metadata,
PropertyType property);
/**
* Fill a property when loading it from a configuration file
*
* @param metadata
*
the metadata to be saved
* @param property
*
the property to be filled
* @param value
*
the value to be set inside the property
*/
public void fillPropertyValue(PropertyMetadata metadata,
PropertyType property, Element value);
}
Properties with units
Units are special kind of metadata attached to a property.
Float, Signed, Unsigned and String properties may have a Combo box that precise the unit
of the property
When the user changes the property's unit, the value may be changed according to the
new unit or not, depending on the return value of the unit handler handle() function that is
called at unit change.
1.
2.
24/38
Typically units metadata are defined as follows:
Unit name = name of the unit
Unit Value = the definition of the units to be used for this unit metadata
Unit Class = com.st.tools.spc5.extensions.UnitHandler
Syntax of value for units is:
DocID024250 Rev 3
UM1610
Creating a new Component project
3.
4.
(<unit1>,<factor1>)[, (<unit2>,<factor2>)...|, (<unitN>,<factorN>)]
Where: <unit_n> is the name of the sub unit, and <factor_n> the float factor to be
used to convert unit to base unit.
There must be a sub unit with factor = 1.0: the base unit
Alternate syntax of value for units is:
<unit1>[, <unit2>,...| <unitN>]
Where: <unit_n> is the name of the sub unit
All those units are affected a factor 1.0
In addition, if only one sub-unit is proposed in the value associated to the "unit"
metadata, then instead of displaying the unit in a Combo, where the user cannot
change the value (only one value), the unit is rendered with a Label widget instead.
Examples of properties with units
Temperature unit definition:
Figure 19: Description element metadata temperature units
Or unit definition,
Figure 20: Description element metadata distance units
Other units definitions:
DocID024250 Rev 3
25/38
Creating a new Component project
UM1610
Figure 21: Description element metadata other units
gives:
Figure 22: Description element metadata other units overview
26/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Testing your XPath expressions
In order to test an XPath expression, the Eclipse XPath testing feature can be used. Follow
these steps:
Open the configuration.xml file with the Eclipse/SPC5Studio XML Editor and select the
XML node from which you want to evaluate the XPath expression.
Figure 23: XPath expressions
From the "Window" menu click on "Show View" and select "XML->XPath".
DocID024250 Rev 3
27/38
Creating a new Component project
UM1610
Figure 24: XPath expressions view
Write your XPath expression and analyze the result in the XPath view.
Figure 25: XPath expressions results
2.3.4
Importance of descriptions
Every extension point element can provide users some description in order to explain its
behaviour.
The SPC5 Extension point provides different types of descriptions:
28/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 26: Description element
Full descriptions
A full description can be used to provide the user with a detailed description of the
associated element. This description will be shown in a box of the UI or in the property
editor view
Extension V1 provides a tag in order to let you show a description in your configuration
page.
Adding an image (for extension V1)
An image can be added to in a configuration or in a group. It also has an alignment
attribute an optional text field.
Such images are displayed beside the optional description text. If the image width is
smallest than the available width it is displayed as is, otherwise it is resized to fit the
available width.
Brief descriptions
A brief description is be used in the property definition. It is shown as a tooltip on the
rendered widget.
2.3.5
Wizards
This SPC5 extension is used to provide SPC5Studio with tools (i.e. the wizard) that can be
invoked by an SPC5Studio component, setting the "wizard" field in SPC5Studio extension
(v1). The wizard will be used to append to the group an external XML (complain with
SPC5Studio component configuration or not); it also imports the group as a root node of an
XML fragment.
DocID024250 Rev 3
29/38
Creating a new Component project
UM1610
Figure 27: Components wizard
The wizard implements the abstract class
com.st.tools.spc5.extensions.AbstractExternalWizard in order to synchronize the
transaction with SPC5Studio configurator.
(see Javadoc of com.st.tools.spc5.extensions.AbstractExternalWizard for a
detailed behaviour).
2.4
Writing templates
The SPC5Studio internal engine uses FMPP based on Freemarker in order to build the
components constituting the user application. In order to write a template, you need to
follow the rules defined in FMPP Manual. The data model passed to the FMPP engine is
described in Section 2.3: "Defining the component data model".
2.4.1
FTL in brief
FMPP is a general-purpose text file preprocessor tool that uses FreeMarker templates. It
can be used to generate source code or any text files.
This is a brief list of FMPP capabilities:
30/38
Preprocessor language (it is the FreeMarker Template Language):
All the usual template constructs, such as include, if/else/elseif, loop.
Macros with named arguments and nested content (body).
Variables (global, or local for a macro call)
Complex expressions using string, arithmetical and logical operations.
Extensible with custom functions.
Automatic and manual escaping (HTML, XML, custom function)
Transforming (filtering) blocks of output; extensible with custom transformations
in Java.
Capturing block of output into a variable.
Charset aware, internally uses UNICODE.
Number and date/time formatting with masks (patterns). Locale sensitive number
and date/time formatting.
DocID024250 Rev 3
UM1610
Creating a new Component project
Bulk file processing:
Process entire directories recursively.
Different file processing modes can be chosen for each file based on path
patterns (as file extension): execute file as template, parse as XML and then
render it to output with a template, binary-copy, ignore.
Can ignore bad source files and log the error message into a text file.
Can guarantee that certain files are processed later than others.
You can expose data from arbitrary data sources be writing extensions in Java.
Currently out-of-the-box supported data sources are:
XML files
CSV and tab-separated text files
Java "properties" files
Ant properties, Ant project and target information
System clock
Plain text files
See Freemarker Template Processor for more details.
2.4.2
The SPC5 data model namespaces
User properties definition
The main part of the component data model can be defined in the component extension
tree. As you will see, each element of data model has a distinguished name that identifies
it. The SPC5Studio Application configurator standardizes names according to the following
rules:
All simbols and spaces are removed and replaced by and underscore '_';
All upper case letters are replaced with the corresponding lower case letter;
For example: if you define a property Stack Size within a group named Runtime Settings, in
order to access this property in the data model via the template processor language, you
need to write ${conf.runtime_settings.stack_size[0]}
Note that all user defined properties are prefixed by the conf keyword.
Global properties
A set of global properties can be also provided to the template engine. Components
developers can not build all such properties, but they can used the in their templates.
Global properties are prefixed by the global keyword.
The following list contains global properties names:
local_component_path: contains the path of the component relative to the containing
project in the workspace
component_name: contains the component name
component_path: contains the component path relative to the containing project in
the workspace (if application is standalone) or absolute file system path (if application
is not standalone)
components: a list of all the components available in the application
includes: a list of all the main headers of each component in the application
inits: a list of all the initialization functions of each component in the application
features: a list of all the features exported by each component in the application. This
data model entry contains the following elements:
count: an integer representing the number of times this feature has been
requested from other components;
DocID024250 Rev 3
31/38
Creating a new Component project
UM1610
exclusive: a boolean value indicating if the feature needs exclusive access;
instances: a hash map containing the instances of all components in the application.
An instance can be retrieved using the component id as the hash map key.
You can use your own Freemarker libraries: put all .ftl libraries in the ftllibs folder
created in the same path of our component folder and import it in your FTL
template.
2.4.3
Examples
The following code shows an example of a component makefile file template:
[#ftl]
[@pp.dropOutputFile /]
[@pp.changeOutputFile name="component.mak" /]
# List of library files exported by the component.
LIB_C_SRC
+= ${global.component_path}/lib/src/hal.c \
${global.component_path}/lib/src/adc.c \
${global.component_path}/lib/src/can.c \
${global.component_path}/lib/src/ext.c \
${global.component_path}/lib/src/gpt.c \
${global.component_path}/lib/src/i2c.c \
${global.component_path}/lib/src/icu.c \
${global.component_path}/lib/src/mac.c \
${global.component_path}/lib/src/pwm.c \
${global.component_path}/lib/src/rtc.c \
${global.component_path}/lib/src/sdc.c \
${global.component_path}/lib/src/spi.c \
${global.component_path}/lib/src/tm.c \
${global.component_path}/lib/src/uart.c \
${global.component_path}/lib/src/usb.c
LIB_CPP_SRC
+=
LIB_ASM_SRC
+=
LIB_INCLUDES
+= ${global.component_path}/lib/include
APP_C_SRC
+=
APP_CPP_SRC
+=
APP_ASM_SRC
+=
APP_INCLUDES
+=
Another example is the following .c source code template in which the data model element
contains more elements that generate the code:
/* Initialization array for the PSMI registers.*/
static const uint8_t spc560p_padsels_init[SPC5_SIU_NUM_PADSELS] = {
[#list conf.groups.i_o_settings.alternate_inputs.psmi_register_settings
[#assign padsel0 = (psmi.padsel_fields.padsel0[0] + ",")?right_pad(5)
[#assign padsel1 = (psmi.padsel_fields.padsel1[0] + ",")?right_pad(5)
[#assign padsel2 = (psmi.padsel_fields.padsel2[0] + ",")?right_pad(5)
[#assign padsel3 = psmi.padsel_fields.padsel3[0] + "," /]
${padsel0} ${padsel1} ${padsel2} ${padsel3}
[/#list]
};
2.5
as psmi]
/]
/]
/]
Testing a component
In order to test the component, you need to run it in another Eclipse instance using Eclipse
tools.
You can run another Eclipse instance from toolbar action, project explorer context menu, or
the menu bar.
32/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 28: Eclipse launch configuration
You can also use the buttons Run/Debug on plugin.xml editor:
Figure 29: Overview
2.6
Deploying a component
In order to deploy the component in SPC5Studio, you need to export it in a suitable format
for the Eclipse environment using Eclipse tools.
You can run plugin export from project explorer context menu or you can use the button
Export on plugin.xml editor:
DocID024250 Rev 3
33/38
Creating a new Component project
UM1610
Figure 30: Project explorer context menu
The following dialog appears:
34/38
DocID024250 Rev 3
UM1610
Creating a new Component project
Figure 31: Export menu
Please read the Eclipse PDE user guide for further insight into all the Plugin
Development Environment features.
DocID024250 Rev 3
35/38
Development references
3
UM1610
Development references
You can find useful topics at the following links:
36/38
Eclipse PDE
Freemarker Template Processor
DocID024250 Rev 3
UM1610
4
Revision history
Revision history
Table 1: Document revision history
Date
Revision
Changes
14-Feb-2013
1
Initial release.
20-Sep-2013
2
Updated Disclaimer.
30-Jul-2014
3
Update content based on new features in SPC5Studio.
DocID024250 Rev 3
37/38
UM1610
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and
improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST
products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order
acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the
design of Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2014 STMicroelectronics – All rights reserved
38/38
DocID024250 Rev 3