Overview
This tutorial takes you through the various development steps involved in building Sedona Framework applications:
- Build a new kit and component
- Build a new scode image
- Build an application
- Run the application
It is recommended that you read the Architecture chapter before exploring this tutorial. Refer to the diagram, which illustrates the work flow this tutorial will take. Also make sure you have your Sedona Framework environment setup correctly before.
Build New Kit
Kits are modules used to organize Sedona code. For this
example we will create a new kit called tutorial
.
In our kit we will create a component called Add
,
which adds two inputs together.
First let's create a directory under src
called "tutorial", with two text files:
src/ tutorial/ +- kit.xml +- Add.sedona
For more information see Structure to see how kits are organized.
The "kit.xml" file is used to define the kit's meta-data for the compiler:
<sedonaKit name="tutorial" vendor="Tridium" description="blah"> <depend on="sys 1.2+" /> <source dir="." /> </sedonaKit>
The "kit.xml" file specifies the name of our kit, a short description, dependencies, and the directories of source code. (The vendor attribute specifies the company that developed the kit - for the purposes of the tutorial leave this as "Tridium" because otherwise the kit name must be prefixed with the vendor name.) For more information see Kits and Compile Kit.
The "Add.sedona" file defines the source code for our new component:
public class Add extends Component { property float out property float in1 property float in2 override void execute() { out := in1 + in2 } }
The Add component is pretty simple - it declares two inputs and an output. When the component is "executed" we add the two inputs and update the output. For more information see Components.
To compile our new kit we just need to run sedonac against our directory or the "kit.xml" file:
C:\Sedona\Sedona-1.2.27\src\tutorial>dir Volume in drive C has no label. Volume Serial Number is 50BC-4286 Directory of C:\Sedona\Sedona-1.2.27\src\tutorial 02/25/2013 09:57 AM <DIR> . 02/25/2013 09:57 AM <DIR> .. 02/25/2013 09:52 AM 160 Add.sedona 02/25/2013 09:55 AM 131 kit.xml 2 File(s) 291 bytes 2 Dir(s) 170,500,431,872 bytes free C:\Sedona\Sedona-1.2.27\src\tutorial>sedonac kit.xml Parse [1 files] WriteKit [C:\Sedona\Sedona-1.2.27\kits\tutorial\tutorial-89858e3e-1.2.27.kit] WriteManifest [C:\Sedona\Sedona-1.2.27\manifests\tutorial\tutorial-89858e3e.xml] *** Success! ***
If successful, you should have a new kit file in your "kits/tutorial" directory. You can open this file in a tool like WinZip to explore the compiler's output. For more information see Sedonac. If you have trouble running sedonac, then see Setup.
Build New Scode Image
Kits are units of deployment, but are not run directly by the SVM. First we have to compile a set of kits into an scode image that can be run directly by the SVM. Create a new directory called "tutorialApp" with one file:
tutorialApp/ +- kits.xml
The "kits.xml" file specifies the kits we wist to compile into an image:
<sedonaCode endian="little" blockSize="4" refSize="4" main="sys::Sys.main" debug="true" test="true" > <depend on="sys 1.2+" /> <depend on="sox 1.2+" /> <depend on="inet 1.2+" /> <depend on="web 1.2+" /> <depend on="func 1.2+" /> <depend on="platWin32 1.2+" /> <depend on="tutorial 1.2+" /> </sedonaCode>
See Sedonac for more information on these settings.
Run sedonac on this file to produce an scode image:
C:\Sedona\Sedona-1.2.27\tutorialApp>sedonac kits.xml ReadKits [7 kits] WriteImage [C:\Sedona\Sedona-1.2.27\tutorialApp\kits.scode] (89088 bytes) +---------------------------------- | Data: 7.8kb (8020 bytes) | Code: 87kb (89088 bytes) | Total: 94.8kb (97108 bytes) +---------------------------------- *** Success! *** C:\Sedona\Sedona-1.2.27\tutorialApp>dir Volume in drive C has no label. Volume Serial Number is 50BC-4286 Directory of C:\Sedona\Sedona-1.2.27\tutorialApp 02/25/2013 10:30 AM <DIR> . 02/25/2013 10:30 AM <DIR> .. 02/25/2013 10:30 AM 89,088 kits.scode 02/25/2013 09:57 AM 336 kits.xml 2 File(s) 89,424 bytes 2 Dir(s) 170,506,817,536 bytes free
If successful, then you should have now have a "kits.scode" file.
Build New App
Sedona is a component oriented language that enables you to build new applications by assembling components. The application file stores a tree of components, their configuration properties, and how they are linked together. Typically applications are built with graphical tools. For this tutorial we will hand code an application file using XML. In the "tutorialApp" directory let's create a new "app.sax" file:
<sedonaApp> <schema> <kit name='sys'/> <kit name='sox'/> <kit name='inet'/> <kit name='web'/> <kit name='func'/> <kit name='platWin32'/> <kit name='tutorial'/> </schema> <app> <comp name="plat" type="platWin32::Win32PlatformService"/> <comp name="users" type="sys::UserService"> <comp name="admin" type="sys::User"> <prop name="cred" val="hE49ksThgAeLkWB3NUU1NWeDO54="/> <prop name="perm" val="2147483647"/> <prop name="prov" val="255"/> </comp> </comp> <comp name="sox" type="sox::SoxService"/> <comp name="web" type="web::WebService"> <prop name="port" val="8080"/> </comp> <comp name="rampA" type="func::Ramp"/> <comp name="rampB" type="func::Ramp"/> <comp name="add" type="tutorial::Add" id="12"/> </app> <links> <link from="/rampA.out" to="/add.in1"/> <link from="/rampB.out" to="/add.in2"/> </links> </sedonaApp>
The file above declares four Service components.
-
The
Win32PlatformService
component provides access to platform properties and other platform-specific features. It is a subclass ofsys::PlatformService
class which provides generic platform functionality. Sedona running on another platform would need a different PlatformService subclass designed for that platform. -
The
UserService
component contains an entry for each authorized user, specifying the user's credentials and privileges. The properties here set up a user named "admin" with a blank password. (Using a blank password for 'admin' should NOT be done on real Sedona devices! We only do it here to simplify the tutorial.) -
The
SoxService
component is required in order to create and use a Sox connection to or from the device. -
The
WebService
component will run an HTTP server so we can use a browser for debugging. The web server's port is set to 8080. (Note that platforms with limited resources may not be able to run a web server.)
func::Ramp
components,
which are used to generate dummy data.
Finally we declare a tutorial::Add
component, which is the component we built ourselves in the step above.
In the links section we create links between the Ramp component outputs and
the inputs to our Add
block to create control flow.
Sedona Framework-enabled devices don't run the XML file directly, so now we need to compile the XML into a binary format that the SVM can use directly. Do this by running sedonac on "app.sax":
C:\Sedona\Sedona-1.2.27\tutorialApp>sedonac app.sax ConvertAppFile [C:\Sedona\Sedona-1.2.27\tutorialApp\app.sax -> C:\Sedona\Sedona-1.2.27\tutorialApp \app.sab] +---------------------------------- | RAM: 14.5kb (14848 bytes) | FLASH: 0.3kb (356 bytes) +---------------------------------- *** Success! ***
Now we should have a file called "app.sab". See Apps for more information.
Run App
If you have followed the steps above, we have:
- Built a new kit called "tutorial" with a component called "Add"
- Compiled our new kit into an scode image called "kits.scode"
- Defined and compiled an app into a file called "app.sab"
At this point we can run our application using the SVM. Assuming we are running on Windows we can run our application as follows:
C:\Sedona\Sedona-1.2.27\tutorialApp>svm kits.scode app.sab Sedona VM 1.2.27 buildDate: Oct 17 2012 08:40:10 endian: little blockSize: 4 refSize: 4 -- MESSAGE [sys::App] starting -- MESSAGE [sox::SoxService] started port=1876 -- MESSAGE [sox::SoxService] DASP Discovery enabled -- MESSAGE [web::WebService] started port=8080 -- MESSAGE [sys::App] running
Here we just pass our code and application filenames to the prebuilt Win32 "svm.exe" executable included with the Sedona open source. If you are running on a different platform you will need an SVM executable designed for that platform - see Porting.
Note that if you plan to restart or reboot the Sedona VM remotely, you should start
the Sedona VM with the --plat
option to run it in "platform mode".
(See Common Commands for more details.)
Now that the SVM is running the application, you should be able to access it with
your browser at http://localhost:8080/.
You can use the "spy" URL
http://localhost:8080/spy/app/12
to view the current values of your tutorial::Add
component.
Hit refresh a couple times to see how the inputs and output change in real-time.
If you have a remote administration tool such as the Sedona Framework Workbench, you should now be able to connect to Sox port 1876 with the username "admin" and empty password. Refer to your Sedona Framework tool documentation for more information.
Success!
Congratulations, you've just built and deployed your first Sedona Framework application! This tutorial illustrates just the very basics of Sedona, using only the command line tools. Continue to explore sedonadev.org to learn more about Sedona and the tools available for managing Sedona devices.