smartobject

A Smart Object Class that helps you with creating IPSO Smart Objects in your JavaScript applications

Table of Contents

1. Overview
2. Installation
3. Usage
4. Resources Planning
5. APIs
6. Code Templates

<a name="Overview"></a>

1. Overview

smartobject is a Smart Object Class that helps you with creating IPSO Smart Objects in your JavaScript applications. If you like to use the IPSO data model in your projects or products, you can use smartobject as the base class to abstract your hardware, sensor modules, or gadgets into plugins (node.js packages) for users convenience. Here is an example of hardware abstraction with mraa on Linkit Smart 7688 in our wiki. In addition, this module is isomorphic and you can use it at server-side as well to generate the smart objects.

IPSO defines a hierarchical data model to describe real-world gadgets, such as temperature sensors and light controllers.

• IPSO uses Object to tell what kind of a gadget is, and uses Object Instance to tell which one a gadget is.
• An Object is like a class or a boilerplate, and each kind of Object has an unique Object Id (oid) defined by IPSO, e.g., 3303 for the Temperature Sensor Object. Here is the list of oids.
• An Object Instance is the entity of an Object. Each Object Instance has an unique Object Instance Id to identify itself from other gadgets of the same class. Simply speaking, oid is like a namespace to manage all the same kind of IPSO Object Instances.
• The Resources are used to describe what attributes may a gadget have, for example, a temperature sensor may have attributes such as sensorValue, unit, minMeaValue, .etc. Resource Values will be filled after instantiated. Here is the list of templates to show you what attributes may a gadget have.

[Note]

• The italics, such Object, Object Id, Object Instance, and Object Instance Id, are used to distinguish the IPSO Objects from the JavaScript objects.

<a name="Installation"></a>

2. Installation

$ npm install smartobject --save

<a name="Usage"></a>

3. Usage

Here is a quick example to show you how to create your Smart Object with only few steps:

• Step 1: Import the SmartObject Class and create an instance from it

  var SmartObject = require('smartobject');
  var so = new SmartObject(); // so can hold many Object Instances in it
  

• Step 2: Initialize a temperature sensor in your smart object so (ref: code templates)

  so.init(
      'temperature',          // 'temperature' is the IPSO-defined Object Identifier (oid, 3303).
      0,                      // 0 is the unique Object Instance Id (iid) assigned by you.
      {                       // This object contains all Resources (attributes) this sensor has.
          sensorValue: 31,    // 'sensorValue' is the IPSO-defined Resource Id (rid, 5700)
          units : 'C'         // 'units' is the IPSO-defined Resource Id (rid, 5701)
      }
  );
  

• Step 3: Initialize more Object Instances. Finally, we have 3 temperature sensors, 1 magnetometer, and 4 digital inputs in our so

  // Init more temperature sensors (each with an unique iid)
  so.init('temperature', 1, {
      sensorValue: 28,
      units : 'C'
  });
  
  so.init('temperature', 2, {
      sensorValue: 72.6,
      units : 'F'
  });
  
  // Init other gadgets
  so.init('magnetometer', 0, {
      xValue: 18,
      yValue: 21,
      zValue: 231
  });
  
  so.init('dIn', 0, { dInState: 1 });
  so.init('dIn', 1, { dInState: 0 });
  so.init('dIn', 6, { dInState: 0 });
  so.init('dIn', 7, {
      // if dInState should be read from by certain operation
      dInState: {
          read: function (cb) {
              var hal = this.parent.hal;  // see SmartObject constructor
              hal.digitalPin0.read(function (err, val) {
                  cb(null, val);
              });
          }
      }
  });
  

<a name="Resources"></a>

4. Resources Planning

The great benefit of using smartobject in your application is that you almost need not to tackle the allocation of Resources by yourself. It provides a scheme to help you with management of reading/writing your hardware or executing a procedure on the machine. All you have to do is to plan and define your Resources well, and then use smartobject methods to do your jobs. You can use smartobject to abstract your hardware, sensor modules, or gadgets into plugins (node.js packages).

Imagine that you have to read the temperature value from a sensor with one-wire interface:

• How to export this sensor to an IPSO smart object?
• How do you read the temperature value from your smart object?
• How do you do with the access control? Your Resource is readable? writable? or remotely executable?

Please refer to Resources Planning Tutorial for more details. It will show you how to initialize your Resources and how to abstract your hardware with IPSO Resources as well. In addition, here are some code templates for your convenience to create smart objects.

<a name="APIs"></a>

5. APIs

• new SmartObject()
• init(), remove()
• objectList()
• has(), get(), set()
• read(), write(), exec()
• dump(), dumpSync()
• isReadable(), isWritable(), isExecutable()

[Note]

• In general, the most often used APIs are new SmartObject(), init(), read(), and write(). It's not that complicated as it looks like.

---

SmartObject Class

Exposed by require('smartobject').

<a name="API_smartobject"></a>

new SmartObject([hal][, setup])

Create an instance of SmartObject class. This document will use so to indicate this kind of instance.

A so can hold many IPSO Object Instances in it. The so itself has an accessible but un-enumerable boolean property 'ipsoOnly' to define if this so only accepts IPSO-defined oid and rid. Default value for so.ipsoOnly is false. You can set it to true in the setup function.

If so.ipsoOnly == true, then the given oid must be an IPSO-defined Object Id, iid must be a number, and all keys within resrcs object must be IPSO-defined Resource Ids, or so.init() will throw Errors.

Arguments:

1. hal (Object): Optional. A component or controller of the hardware abstraction layer. It will be assigned to this.hal at creation of a so. Noted that so.hal is accessible but un-enumerable.
2. setup (Function): Optional. A setup function allows you to do some initializing work, for example, setting gpio direction. In the setup function, this will be bound to the so itself, thus you can use this.hal to access your hardware.

Returns:

• (Object): so

Examples:

• A very simple case. There is no hardware with the smart object. For example, at server-side we only need the data of a smart object, thus we don't have the hal.

var SmartObject = require('smartobject');

var so = new SmartObject();

• No hardware, and you like to make so accept only IPSO-defined identifiers.

var SmartObject = require('smartobject');

var so = new SmartObject(function () {
    this.ipsoOnly = true;
});

• We have 2 LEDs and 1 Switch controlled via mraa. This is a typical example at client-side (machine).

var m = require('mraa');
var SmartObject = require('smartobject');

var myHardware = {
    led1: new m.Gpio(44),
    led2: new m.Gpio(44),
    onOffSwitch: new m.Gpio(45),
    foo: 'bar'
};

var so = new SmartObject(myHardware, function () {
    var hal = this.hal;

    // hardware initialization
    hal.led1.dir(m.DIR_OUT);
    hal.led2.dir(m.DIR_OUT);
    hal.onOffSwitch.dir(m.DIR_IN);

    hal.foo = 'initialized';
    this.ipsoOnly = true;
});

---

<a name="API_init"></a>

init(oid, iid, resrcs[, setup])

Create and initialize an Object Instance in so, where oid is the IPSO Object Id to indicate what kind of your gadget is, iid is the Object Instance Id, and resrcs is an object that wraps up all the Resources.

• Be careful, invoking init() against an existing Object Instance will firstl