Overview

This section covers integration of the Sedona Framework with the Niagara AX Framework.

Sedona Framework components in Niagara
Provisioning Sedona Framework-enabled devices from Niagara

Sedona Framework Components in Niagara

This section details how to write Sedona Framework components in such a way that they can be easily integrated with the Niagara AX component architecture. This section will help developers familiar with the Niagara AX Framework to understand how Sedona idioms translate to Niagara idioms. In particular, this section will detail various aspects of programming Sedona Framework components so that the user experience inside Workbench is very similar to that of using standard BComponents in Niagara.

How Niagara uses sys::Facets when modeling Sedona Framework Components
Niagara Views on Sedona Framework Components

In Niagara, all Sedona Framework components are modeled as a special kind of BComponent called BSedonaComponent. Regardless of your Sedona Framework component type, it will be modeled as a BSedonaComponent, which essentially wraps your sys::Component type. The primary means of communicating information about a Sedona Framework component type and its slots to Niagara is by using sys::Facets. The following tables detail which facets are recognized by Niagara, and how they are used when Niagara constructs a BSedonaComponent to model your sys::Component.

Sedona Framework Component Facets

The following table lists the facets for a sys::Component type that Niagara will recognize.

Facet	Type	Description
niagaraIcon	Str	The Ord to the location of the icon to use for this component.
palette	bool	If set to false, then the type will not be displayed in the Sedona Palette. Otherwise, it will be shown in the palette.

Examples

@niagaraIcon="module://icons/x16/control/math/add.png"
public class Add2 extends Component { ... }

@palette=false
public class CommonBase extends Component { ... }

Sedona Framework Slot Facets

BComponent slot flags

If you define a facet on your Sedona component slot that has the same name as a Niagara flag, and its value is true or false, then the corresponding slot in the BSedonaComponent will be likewise set; otherwise, the facet will simply be treated like all other facets (see BComponent facet list). The most common slot flags to set are listed in the table below.

Facet	Description
readonly	The `readonly` flag is used to indicate slots that cannot be changed by the user.
hidden	Hidden slots are designed to be invisible to the user, and exist only for Java developers. User interfaces should rarely display hidden slots.
summary	Summary properties are the focal points of any given BComponent. This flag is used by user interface tools to indicate primary properties for display. This might be as a column in a table, or as a glyph in a graphical programming tool. All Sedona runtime slots are treated as summary unless the summary facet is explicitly set to false: `@summary=false`.
confirmRequired	When the action is invoked by a user, a confirmation dialog must be acknowledged before proceeding.
operator	This gives a slot an operator security level. By default when this flag is clear, the slot has an admin security level.
noAudit	Setting this flag prevents property changes and action invocations from being audited.

Examples

public class Foo extends Component
{
  ...

  // Require the user to confirm that they actually
  // want to reboot the system before executing the action.
  @confirmRequired
  action void reboot() { ... }

  // Don't want UI to allow user to edit password property
  @config @readonly @asStr property Buf(17) password

  // This slot we don't want displayed to users, but we
  // want operators to be allowed to change it.
  @hidden @operator property int debugLevel = 0
}

Note: See Component Properties for a discussion of @config and other Sedona-only facets.

If a slot facet does not match a Niagara flag name, then it will stored as a a BFacet for the slot. Some BFacets have a special meaning in Niagara. This table lists some of the more common BFacets.

Facet	Type	Description
min	number	Used to specify the minimum value for a number, or the minimum number of characters in a Str.
max	number	Used to specify the maximum value for a number, or the maximum number of characters in a Str.
unit	Str	Display text that describes the property's units.
precision	int	Used with floating point numbers to define the number of digits after the decimal point.
radix	int	Used with integers to qualify base radix.
showSeparators	bool	Used with numerics to enable/disable displaying of separators between every 3 digits (e.g. 10,000 vs. 10000).
multiLine	bool	Used with Str to support a multiline editor.
fieldWidth	int	Used with Str to specify the number of columns in a text field.
allowNull	bool	Tells the field editor allow the value to be set to null.
fieldEditor	Str	Indicates the BTypeSpec of the field editor to use for editing a property value. It overrides the default field editor registered for the property's value.
trueText	Str	Display text to be used for a boolean property when true.
falseText	Str	Display text to be used for a boolean property when false.
nullText	Str	Display text to be used for a boolean property when null.

Examples

public class Foo extends Component
{
  ...

  // Property for password - must be at least 8 chars long
  // and no more than 16.
  @min=8 @max=16
  @config @asStr property Buf(17) pwd

  // The debug level should be specified in base 16.
  @radix=16 @min=0 @config
  property int dbgLevel = 0x1234
}

Niagara Views on Sedona Framework Components

Normally in Niagara, views are registered on a BTypeSpec by using the <agent/> specification in the module-include.xml file of your module. However, since all Sedona Framework components are modeled as BSedonaComponents in Niagara, a different mechanism is used to register views on your Sedona Framework component. Namely, <def/> blocks are used to define agents on specific Sedona Framework component types. An example follows.

Suppose you have developed a Service called MyService in kit foo. The qname for this type is foo::MyService. Suppose, further, that you have written a Niagara view BMyServiceView to manage this service and that it resides in module bar. The BTypeSpec for this service is bar:MyServiceView. To register your view on the MyService service, you would add the following lines to the module-include.xml for your module:

<defs>
  <!-- This declares the agent on the foo::MyService service -->
  <def name="sedona.foo::MyService#agent" value="bar:MyServiceView" />
</def>

<types>
  ...
  <!-- Declare the Niagara type as usual, but no agent block is required -->
  <type name="MyServiceView" class="com.bar.BMyServiceView" />
  ...
</types>

When your view loads, a BISedonaComponent will be passed to the doLoadValue method of your view.

protected void doLoadValue(BObject value, Context cx) throws Exception
{
  BISedonaComponent myService = (BISedonaComponent)value;
  // See the javax.baja.sedona.sys.BISedonaComponent interface
  // for more details.
}

Note: the concrete class BSedonaComponent is deprecated as of the TXS 1.1 release. You should migrate your views to use the new BISedonaComponent interface instead. If you have questions about writing views for Sedona Framework components, ask them on one of the Sedona Framework forums on Niagara Central.

Provisioning Sedona Framework platforms from Niagara

When using Niagara tools to provision a Sedona Framework-enabled device, there are a few things to be aware of.

File names

Niagara makes assumptions about the file names used to launch the remote platform. In particular, it assumes: the SVM is named "svm.bin" (or "svm.exe"), the kit bundle file is named "kits.scode", and the app binary is named "app.sab".

File PUT

To be Sox compliant, Sedona Framework platforms must use app.sab as the file name of the app to run, and kits.scode as the file name of the scode image to run. Further, to be Sox compliant, a platform must look for an app.sab.stage and a kits.scode.stage file when starting and rename them to app.sab and kits.scode respectively before the SVM attempts to load the app and scode.

Hence, when Niagara writes new app and scode files to the device, it does so in three stages:

Writes the app as app.sab.writing and the scode as kits.scode.writing.
Renames those files to app.sab.stage and kits.scode.stage respectively.
Restarts the device.

File GET

A file GET operation from Sedona to Niagara should prompt the user for the path and filename to be used on the local host for the received file. The name of the file as it is being transferred is normally not visible (or relevant) to the user.

Niagara AX

Overview

Sedona Framework Components in Niagara

Sedona Framework Component Facets

Sedona Framework Slot Facets

BComponent slot flags

BComponent slot facets

Niagara Views on Sedona Framework Components

Provisioning Sedona Framework platforms from Niagara