A Sedona Framework platform is simply any device running an SVM. The platform is uniquely identified by the platformId property of the platform service running in the app on that device.

This section presents a high-level, step-by-step guide to creating a Sedona Framework platform for your own device. We will use the Win32 platform provided in the open source distribution as a case study in creating a new Sedona Framework platform.

Step 1: Create a kit for your platform service
Step 2: Create a platform definition file
Step 3: Port the SVM
Step 4: Build the SVM
Step 5: Create a PAR file
Step 6: SAX and Scode setup for your platform

Step 1: Create a kit for your platform service

Every app must have a sys::PlatformService component running in it. The platform service is intended to represent your unique OS/Hardware platform. One of the most important properties on the platform service is the platformId property. This property uniquely identifies your platform, and should normally map to a platform stored in the platform database.

The platform service provided in the sys kit is simply hard-coded to return a platform id of "unknown". You will need to provide a sub-class of the sys::PlatformService so that, at the very least, you can set the platformId properly. Therefore, you will usually create a new kit for your platform service. The win32 platform service is in a kit called "platWin32" and the kit definition file is in sedona_home/platforms/src/generic/win32/kit.xml

The Win32PlatformService.sedona provides a common implementation of a platform service. You can find this file in sedona_home/platforms/src/generic/win32. We override the start() method so that we can make a native call to the device to get the platform id for that device.

class Win32PlatformService extends PlatformService {

  internal native Str doPlatformId()

  override virtual void start() {
    super.start()
    updatePlatformId(doPlatformId())
  }
}

The native implementation of doPlatformId() for our win32 platform is

#include "sedona.h"
#include "sedonaPlatform.h"
#include <windows.h>

// Str Win32PlatformService.doPlatformId()
Cell platWin32_Win32PlatformService_doPlatformId(SedonaVM* vm, Cell* params)
{
  Cell result;
  result.aval = PLATFORM_ID;
  return result;
}

Notice that our native implementation makes use of the sedonaPlatform.h header file that was generated based on our platform definition XML file. The benefit of this approach is that we can dynamically change the implementation of the underlying SVM without having to create distinct platform services for all those unique configurations. The next step describes how to create the platform definition for our win32 platform.

Step 2: Create a platform definition XML file

Please refer to the section on platform definition for an in depth discussion of this file.

The platform definition for the win32 platform is located in sedona_home/platforms/src/generic/win32/generic-win32.xml.

<sedonaPlatform vendor="Tridium" id="tridium-generic-win32-${sedona.env.version}" >

  <compile endian="little" blockSize="4" refSize="4" debug="true" test="true">

    <!-- Native Kits -->
    <nativeKit depend="sys 1.0" />
    <nativeKit depend="inet 1.0" />
    <nativeKit depend="datetimeStd 1.0" />
    <nativeKit depend="platWin32 1.0" />

    <!-- Native Sources -->
    <nativeSource path="/src/vm" />
    <nativeSource path="/src/sys/native" />
    <nativeSource path="/src/sys/native/std" />
    <nativeSource path="/src/sys/native/win32" />
    <nativeSource path="/src/inet/native" />
    <nativeSource path="/src/inet/native/std" />
    <nativeSource path="/src/inet/native/sha1" />
    <nativeSource path="/src/datetimeStd/native/std" />
    <nativeSource path="/platforms/src/generic/win32/native" />
  </compile>

</sedonaPlatform>

There are a few things to note about our platform definition.

We have specified the id attribute for our platform. Later, when we run sedonac on this file to stage the source, we can expect the sedonaPlatform.h header file to be generated. This is what our doPlatformId() native code used to set the platform id.
Our SVM will only be able to support the native methods from the sys, inet, datetimeStd, and platWin32 kits because of our <nativeKit> declarations.

Step 3: Port the SVM

This process is already described in detail in the porting section. We specified in our platform definition where all the native source code would be located for our SVM. Typically, as we are porting the SVM we will need to update our platform definition so that it references all the correct locations for the native code in the <nativeSource> directives.

Refer to the platform definition for our win32 platform to see where all the native code for SVM resides and how it was implemented.

Step 4: Build the SVM

As we are porting our SVM, we will want to periodically build it so that we can test it. As described in the staging section, we can use sedonac to stage all native source files in one directory. Then we must develop our own build scripts (native tool-chain) to actually build the SVM.

The open source distribution includes a makewinvm.py script that will build our win32 platform SVM. It will run sedonac on our generic-win32.xml platform definition file to stage all the source code for the SVM, and then it will compile the source code into a binary. This is the svm.exe that you will find in the bin/ directory of the open source distribution. To run this script you must have setup your environment for development.

You must provide your own native tool-chain to accomplish the same tasks for your platform.

Step 5: Create a PAR file for your platform

Refer to the section on PAR files for a more in-depth discussion on PAR files.

When we staged our native source by running sedonac on our platform definition, it also staged a .par/ directory for us. Since we specified a platform id attribute in our platform definition, the platformManifest.xml in that directory is valid. Therefore, all we need to do is zip up the contents of that directory and use the platformdb.py script to install it in our platform database.

The makewinvm.py script does this for the open source win32 platform. If you issue the platformdb.py --list command you should see output similar to the following

D:\sedona\baseline\pub>platformdb.py --list
tridium-generic-win32-1.0.46

This output indicates that the we have successfully installed our win32 platform into the platform database. You will need to make it part of the native tool-chain for your platform to create the PAR file and install it into the platform database. You can use the platformdb -i <par file> command to install a PAR file into the platform database.

Step 6: SAX and Scode setup for your platform

To use your new platform service, you will need to create an application (SAX) that uses your platform service. There is an example SAX file that uses the Win32PlatformService at sedona_home/apps/platWin32.sax. You can use this file as a template and make the following modifications to use your platforms service:

In the <schema> section, remove the platWin32 kit and add the kit for your platform service.
In the <app> section there is a component called "plat". Change the type of that component from "platWin32::Win32PlatformService" to the type of your platform service.

After you have made these changes you can run sedonac on your new SAX file to create an binary application (SAB) that your SVM can run.

Finally, you will need to create a scode image corresponding to the kits in your SAX. There is an example scode configuration file in sedona_homde/scode/platWin32.xml. You can use this file as a template and make the following modification for your platform:

Modify the <sedonaCode> elements to match the settings for your device. For example, make sure the blockSize, refSize, endian, etc. are correct.
Remove the dependency on the "platWin32 1.0" and add a dependency for the kit containing your platform service.