Sedona

Index | Prev | Next

Tutorial

Overview

This tutorial takes you through the various development steps involved in building Sedona Framework applications:

  1. Build a new kit and component
  2. Build a new scode image
  3. Build an application
  4. 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 called "tutorial" with two files: 

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.0" />
  <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 Sedonac.

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: 

D:\sedona\src\tutorial>dir

 Directory of D:\sedona\src\tutorial

01/19/2009  01:55 PM   149 Add.sedona
01/19/2009  01:55 PM   258 kit.xml

D:\sedona\src\tutorial>sedonac kit.xml
  Parse [1 files]
  WriteKit [D:\sedona\kits\tutorial\tutorial-89858e3e-1.0.30.kit]
*** 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.0" />
  <depend on="sox 1.0" />
  <depend on="inet 1.0" />
  <depend on="web 1.0" />
  <depend on="control 1.0" />
  <depend on="tutorial 1.0" />
</sedonaCode>

If you are running on 32-bit x86 then you can use the exact file listed above. Otherwise you might need to tweak your settings for endian and refSize. See Sedonac for more information.

Run sedonac on this file to produce an scode image: 

D:\sedona\tutorialApp>sedonac kits.xml
  ReadKits [6 kits]
  WriteImage [D:\sedona\tutorialApp\kits.scode] (79340 bytes)
  +----------------------------------
  |  Data:      6.3kb (6448 bytes)
  |  Code:     77.5kb (79340 bytes)
  |  Total:    83.8kb (85788 bytes)
  +----------------------------------
*** Success! ***

D:\sedona\tutorialApp>dir

 Directory of D:\sedona\pub\tutorialApp

01/19/2009  02:24 PM    79,340 kits.scode
01/19/2009  02:20 PM       342 kits.xml

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='control'/>
  <kit name='tutorial'/>
</schema>
<app>
  <comp name="plat" type="sys::PlatformService"/>
  <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="control::Ramp"/>
  <comp name="rampB" type="control::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.

We then declare two control::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": 

D:\sedona\tutorialApp>sedonac app.sax
  ConvertAppFile [D:\sedona\tutorialApp\app.sax -> D:\sedona\tutorialApp\app.sab]
  +----------------------------------
  |  RAM:     12.1kb (12432 bytes)
  |  FLASH:    0.2kb (207 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:

At this point we can run our application using the SVM. Assuming we are running on Windows we can run our application as follows: 

D:\sedona\tutorialApp>svm kits.scode app.sab

Sedona VM 1.0
buildDate: Dec  2 2008 12:58:55
endian:    little
blockSize: 4
refSize:   4

-- MESSAGE [sys::App] starting
-- MESSAGE [sox::SoxService] started port=1876
-- MESSAGE [web::WebService] started port=8080
-- MESSAGE [sys::App] running

We just pass our code and application filenames to the "svm.exe" executable. If you are running on an alternate platform, you might need to compile the SVM from source - see Porting.

Assuming you have your SVM running the application, you should be able to hit it with your browser at http://localhost:8080/. If you go to the URL http://localhost:8080/spy/app/12 you should see 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 programming 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.

Congratulations, you've just built and deployed your first Sedona Framework application! Remember this tutorial illustrates the very basics using only the command line tools. Visit sedonadev.org to learn more about the Sedona tools available.

Index | Prev | Next