Please note, this documentation is for version 2.0 of BajaScript released with Niagara 4.0.

BajaScript is a framework for building web applications. It's an API for getting data. It's not a User Interface library. If you want to create User Interfaces, please refer to the bajaux documentation after you've learnt about BajaScript...

  • Browser Based: BajaScript is written in JavaScript. It's a framework that runs in the browser.
  • Open Web: BajaScript is built upon standard open web technologies. This opens up the power of the Niagara framework to the general web community. An application written with BajaScript and other open web technologies will run on virtually every platform currently available including PCs, Smart Phones and Tablets.
  • Remote Programming API: BajaScript is a remote programming API for a Station.
  • Live: BajaScript can be used to view and subscribe to live data in a Station.
  • Configuration: BajaScript can be used to configure any part of a Station. This can be anything from commissioning a driver to configuring logic on a Wiresheet.
  • Querying: BajaScript can be used to query any information in a Station (i.e. points, alarms, histories etc).
  • Small Footprint: even though BajaScript is extremely powerful, it has a small foot print.
  • High Fidelity: when using BajaScript to remotely configure a Station, the Components and Objects in the Station are also represented in BajaScript. The remote BajaScript Components and Objects look and feel just like their original Java based counterparts running in a Station.
  • Niagara Reinvented for the Web: BajaScript reinvents the original Java based Niagara APIs in JavaScript. Anyone who's familiar with developing Components and Objects in Niagara will be familiar with BajaScript's APIs. Everything from the Type and Registry System to the Component and Object model has been recreated in JavaScript.

Background

Why create BajaScript?

We no longer live in an age where computing is dominated by PCs. We live in an age of smart Internet devices. The new age of the web is built upon open web technologies such as HTML, CSS and JavaScript. BajaScript is a framework written in JavaScript that enables web developers to innovate and build the next generation of smart building web applications that targets not just one but all of these platforms.

Why JavaScript?

JavaScript is a powerful Object Oriented scripting language. It's also the lingua franca of the web that runs in all modern web browsers. Over the last few years, web browsers' JavaScript engines have got faster and faster. Combined with the new emerging HTML5 standard, this has opened new possibilities for developing sophisticated open web applications.

Is BajaScript a User Interface technology?

No. BajaScript is a remote data JavaScript API. A developer can use any web based user interface technology they want to with BajaScript.

Why the Open Web?

Every PC, Smart Phone and Smart Pad has a powerful modern web browser available for it. In fact they're so powerful, entire applications can be created to run in the browser. An application built using open web technology will run on any modern web browser. Tridium is a world leader in open building control technology. Therefore, it makes sense for us to embrace open technology for the web in much the same way as we do for buildings.

What about native Apps for Smart Phones?

The world's PC market is saturated. The uptake of Smart Phone and Tablets is extremely rapid and is fuelling a worldwide technological and innovation revolution. At the same time, this market is extremely fragmented. At the time of writing there is no clear winner in this marketplace.

Some Smart Phone manufacturers insist that developers build native web applications. Even though native web applications do run very quickly, the application will only run on that particular manufacturer's device. This is great for the Smart Phone manufacturer but bad for the user as they're locked into a particular platform. However, all Smart phones do have modern web browsers with great HTML, CSS and JavaScript support. There are technologies/frameworks currently available that enable developers to wrap up browser based web apps into native Apps for a particular platform. Phonegap is just one of these enabling technologies that enables web developers to create Apps that target every major Smart Phone and Tablet platform.

Approach

Gone are the days of hacking JavaScript up in a simple text editor and hoping for the best when it's run in a browser. There are powerful tools now available on the web, that enable a developer to write solid JavaScript code. BajaScript was developed using JsHint. Also, like any good object oriented software, BajaScript has many thousands of unit tests to ensure it's robust as possible.

Technical Overview

BajaScript is built from JavaScript in much the same way as Niagara's Baja standard is built from Java. To use BajaScript, you will need to know JavaScript. Of course, there's a plethora of resources for learning how to professionally develop web applications using JavaScript available on the web.

BajaScript is high fidelity. The Component and Object architecture has been recreated in BajaScript. Therefore, all the things a Niagara developer is familiar with such as ORDs, Slots, Types and Simples are all available to use.

The protocol used between BajaScript and the Station is called BOX (Building Object eXchange). BOX is a pure JSON based protocol. BOX is currently considered a private protocol until the API has matured. BOX has been designed for high performance. Why is BajaScript not using oBIX as the protocol? oBIX is an excellent restful Web Service that Tridium are dedicated to supporting and developing further. However, you can't do all the things with it that BajaScript needs to do (i.e. querying, adding, removing, reordering etc). Also oBIX is not high fidelity enough; it has its own granular type system that Niagara fits into. Indeed oBIX could have been made to do all of these things, however it would have complicated and bloated a rather elegant standard that's already become a global success story. Also as JSON is faster to parse and easier to manage in a browser, it made sense to create a new protocol for BajaScript. It entirely depends on your use case on whether you should use BajaScript or oBIX.

Technical Features

For those of you who are already Niagara developers, here's an overview of some of the core BajaScript features...

Type and Registry System

At the very heart of Niagara is a Type System. All Objects and Components in Niagara have a Type. Types are held in the Niagara Registry. In Niagara, a Type typically maps to a Java class. A similar Type and Registry System has been created in BajaScript. Of course, there are some key differences...

  • Lazily loading: Types are lazily loaded into BajaScript on demand. This makes BajaScript light and scalable.
  • Types map to JavaScript Constructors: in BajaScript, Types map to JavaScript Constructors. This makes BajaScript fully extensible and allows it to emulate the core functionality of the Niagara framework. In Niagara, a Complex Type (Complex is the base class for all Niagara Components) can have frozen Slots. All Complex Types with frozen Slots (and Frozen Enumerations) are stored as special Contracts. This is the similar principle to oBIX Contracts. This provides BajaScript with all the necessary information to create high fidelity Components and Objects.

High Fidelity

High fideltity is a term used in BajaScript to describe how BajaScript Components and Objects look and feel just like their original Java based counterparts. For instance, let's use the popular BNumericWritable control point Type from Niagara...

  • Input Properties: this Type has multiple input Properties (in1 to in16 and a fallback). Some of these Properties are writable and can be changed through a Niagara Property Sheet.
  • Output Properties: this Type has a readonly output Property (out).
  • Actions: this Type has has multiple Actions (set, override etc). These Actions can be invoked on the point. Some of these Actions require arguments when invoked.
  • Methods: BNumericWritable extends from BComponent (further up the inheritance chain). BComponent has many methods exposed so developers can add, remove, rename, reorder, set and get Slots. The remarkable thing is when the above point is instantiated as a BajaScript Component, all of this information is recreated. Therefore, a BajaScript version of BNumericWritable has Slots, Flags, Facets, the friendly Property getters/setters and Action invocation methods.

The core Simples have also been reproduced in BajaScript. Therefore, the Niagara Type BDouble maps to a JavaScript Number, BString maps to String, BRelTime maps to baja.RelTime etc.

BajaScript has Type matching. Let's say there's a Type in Niagara that doesn't have a dedicated JavaScript constructor in BajaScript (i.e. BNumericWritable). In this case, BajaScript examines the Type's Super-Type chain until it finds JavaScript Constructor to use. This enables BajaScript to compentently reproduce any Type in the Niagara framework.

Caching

BajaScript uses same Type of Caching mechanism that Workbench uses when communicating with a Station. A mini-lazily loading version of the Station is stored and maintained in BajaScript. This avoids unnecessary network calls and provides a nice pluggable way to listen for Component events (much like a Web Developer listening to the DOM for HTML events).

ORDs

ORDs (Object Resolution Descriptors) are how a developer resolves Station information. The same principle is used in BajaScript.

Asynchronous

When using remote programming in Niagara, the API predominantly uses synchronous network calls. In order for a Web Application to function correctly (and the page not to block), asynchronous network calls must be used. Therefore, some of the core APIs have been redesigned to work well in an asynchronous way.

Security

All security checks are enforced at the Server using Niagara's own proven Security model.

Batching

Most network calls can be batched together into own HTTP request. This enables developers to write efficient code that doesn't overburden the network.

BajaScript has many more features that are too numerous to mention in this summary. As a Niagara developer, you take a lot of these features for granted. We think you'll be pleasantly surprised at how many features have been recreated in BajaScript.

Click here to get started!