Document
Everything about obniz

Websocket API

Everything obniz can do

About Websocket API

obniz is fully controllable by sending json to Websocket API.

obniz.js warps this API. You can include obniz.js on html by adding script tag. And Also installing from npm is avaiable.

This page shows all Websocket API details used by inside of obniz.js.

Endpoint

Each obniz has different API Endpoint.
You can check your path on obniz cloud console.
https://obniz.io/cloud ​

JSON

All communication on Websocket is JSON. Control obniz by sending JSON. And receive JSON from obniz.

Handshake

ready

all things ready

{
  ws: {
    ready: true
  }
}

rediredt

If the server required you to connect other endpoint to communicate with your obniz. This json will be sent.

{
  ws: {
    redirect: "wss://anotherserver.com"
  }
}

IO

available 0~11

output

{
  io1: false/true
}

output

{
  io1: {
    direction: "output",
    value: true/false
  }
}

input value onece(stream=false)

{
  io1: "get"
}

input value

{
  io1: {
    direction: "input",
    stream: true/false(default)
  }
}

output type

{
  io1: {
      output_type: "push-pull5v"(default) or "push-pull3v" or "open-drain"
  }
}

pullup

{
  io1: {
      pull_type: "pull-up5v" or "pull-up3v" or "pulldown" or "float"
  }
}

notify value

{
  io1: false/true
}

IO Animation

io animation is hardware acceleration for serial sequence change of io. now "loop" animation is avaiable. it loop io changes regarding json array. io and pwm json commands only. duration is how long does it state consist. It msec. 1 to 429426 msec (around 1 hour).

{
  io: {
    animation: {
      name: "animation-1", // identifier for this io animation. 1 to 254 character
      status: "loop",
      states: [{
        duration: 10, // 10 msec
        state :{
          io0: false,
          io1: true
        }},{
        duration: 10,
        state :{
          io0: true,
          io1: false
        }}]
    }
  }
}

pause io animation

{
  io: {
    animation: {
      name: "animation-1",
      status: "pause"
    }
  }
}

resume io animation

{
  io: {
    animation: {
      name: "animation-1",
      status: "resume"
    }
  }
}

PWM

available 0 to 5

initialize

{
    pwm0: {
        io: 1
    }    
}

set frequency

{
    pwm0: {
        freq: 1000 ( hz )
    }
}

set duty

{
    pwm0: {
        pulse: 0.001 ( msec )
    }
}

set duty with duty ratio

{
    pwm0: {
        duty: 50 ( % )
    }
}

modulation

{
    pwm0: {
        modulate: {
          type: "am" (only "am" available),
          symbol_sec: 0.001,
          data: [0, 255, 255]
        }
    }
}

de initialize

{
    pwm0: null
}

UART

available 0 to 1

initialize

{
    uart0: {
        rx: 0,
        tx: 1Z,
        baud: 115200, (optional default 115200)
        stop: 1, (optional 1(default)/1.5/2),
        bits: 8,  (optional 8(default)/5,6,7)
        parity: "off", (optional off(default)/odd/even)
        flowcontrol: "off" (optional off(default)/rts/cts/rts-cts)
        rts: 2 (optional. io number)
        cts: 3 (optional. io number)
    }
}

send

{
    uart0: {
        data: [2, 252]
    }
}

notify received

{
    uart0: {
        data: [255, 39, 123]
    }
}

deinitialize

{
    uart0: null
}

SPI

available spi0, spi1

init

clk, mosi, and miso can be empty. But specify at least one.

{
    spi0: {
        mode: "master",
        clk: 0,
        mosi: 1,
        miso: 2,
        clock: 1000000
    }
}

// clk and mosi only
{
    spi0: {
        mode: "master",
        clk: 0,
        mosi: 1,
        clock: 1000000
    }
}

// mosi only
{
    spi0: {
        mode: "master",
        mosi: 0,
        clock: 1000000
    }
}

write without receive

{
    spi0:{
        data: [0x73, 0x83, 0x74],
        read: false
    }   
}

write and read

{
    spi0:{
        data: [0x73, 0x83, 0x74],
        read: true
    }   
}

notify readed

{
    spi0: {
        data: [37, 75, 34]
    }
}

deinit

{
    spi0: null
}

I2C

available only i2c0

init

if pullup is not defined or selected "pull-up" then clock is limited <= 100khz. We recommend use external pull-up resistor.

{
    i2c0: {
        sda: 0,  // io used by SDA
        scl: 1   // io used by SCL
        clock: 400000 // clock frequency at hz
        mode: "master",
        pull_type: "float" or "pullup"(default) or "pullup5v"
        slave_address_length: 7(default) or 10 // only when mode="slave"
        slave_address: 0x9874  // only when mode="slave"
    }
}

write

if address over 0b01111111; then address treated as 10bit address automatically. or specify address_bits: 10 to force 10bit address mode.

{
    i2c0: {
        address: 0x37, 
        address_bits: optional. 7(default) or 10,
        data: [0, 1, 2]  // including
    }
}

read request

if address over 0b01111111; then address treated as 10bit address automatically.

{
    i2c0: {
        address: 37,
        address_bits: optional. 7(default) or 10,
        read: 3 // 3byte read
    }
}

notify readed

{
    i2c0: {
        address: 37,
        data: [37, 75]
    }
}

deinit

{
    i2c0: null
}

Display

text

{
    display: {
        text: "Hello World!"
    }
}

clear

{
    display: {
        clear: true
    }
}

qr

{
    display: {
        qr: {
          text: "https://obniz.io/",
          correction: "L" or "M"(default) or "Q" or "H"
        }
    }
}

render raw bytes.

1 bit represents 1 dot. 1=white, 0=black. 1 byte is part of one line. Order is same like.
{1byte} {2byte} {3byte}...{16byte}
{17byte} {18byte} {19byte}...
.....
.....................{1024byte}

{
    display: {
        raw: [255, 255,,,,,] // msut be 128*64 bits(=1024byte)
    }
}

Switch

the switch embed on obniz itself. If it's state is changed, notification will be fired.

notify state

{
  switch:{
    state: "none" or "push" or "left" or "right"
  }
}

get current state

{
  switch: "get"
}

response

{
  switch:{
    state: "none" or "push" or "left" or "right",
    action: "get"
  }
}

available ad0~ad11

enable & start ad module at io. specify stream true to continurous notifying on voltage change.

{
    ad0: {
        stream: true/false(default)
    }
}

notify

{
    ad0: 3.300  (volt)
}

stop ad.

{
    ad0: null
}

BLE

advertisment start

{
     ble : {
        advertisement: {
             adv_data : [0x00, 0x00, ... ],   //required. array of advertise data (max length : 31)
             scan_resp : [0x00, 0x00, ... ],  //optional. array of scan response data (max length : 31) 
        }
     }
}

advertisment stop

{
     ble : {
        advertisement: null
     }
}

scan start

{
     ble : {
        scan : {
             duration : 30,  //optinal.  scan time seconds. default 30sec
        } 
     }
}

scan stop

{
     ble : {
        scan : null
     }
}

scan callback

{
     ble : {
        scan_results : [
            {
              event_type: inquiry_result,  //inquiry_result for discovered one pheripheral,
                                           //inquiry_complete for timeout scan duration
              address: "abcdef012345" // device address (hex string)
              device_type: "ble"   //ble, dumo, or breder
              address_type: "public",  //public ,random, rpa_public, or rpa_random
              rssi: -22                           //rssi (signed number0
              adv_data:  [0x00, 0x00, ...],  //advertise data 
              scan_resp: [0x00, 0x00, ...]               //scan reponse data
            },
            { ... }, ... 
        ]
     }
}

connect

{
     ble  : {
        connect :  {
             address : "abcdef012345",  //required.  
        } 
     }
}

disconnect

{
     ble  : {
        disconnect  : {
             address : "abcdef012345",  //required.  
        } 
     }
}

on connect/disconnect callback

{
     ble : {
        status_updates : [ 
            {
                address : "abcdef012345",
                status : "connected",   //connected or disconnected
            },
            { ... }, ...
        ] 
     }
}

get service

{
     ble : {
        get_services : {
             address : "abcdef012345",  //required.  
        } 
     }
}

on get service callback

{
     ble : {
        get_service_results : [ 
            {
                address : "abcdef012345",
                service_uuid : "FF00",   //hex string
            },
            { ... }, ...
        ] 
     }
}

get characteristics

{
     ble : {
        get_characteristics : {
             address : "abcdef012345",  //required. 
             service_uuid :   "FF00",  //required.  
        } 
     }
}

get characteristics callback

{
     ble : {
        get_characteristic_results : [ 
            {
                address : "abcdef012345",
                service_uuid : "FF00",   //hex string
                characteristic_uuid : "FF01",   //hex string
            },
            { ... }, ...
        ] 
     }
}

read characteristic

{
     ble : {
        read_characteristic : {
             address : "abcdef012345",  //required. 
             service_uuid :   "FF00",  //required.  
             chracteristic_uuid :  "FF01",  //required.  
        } 
     }
}

read characteristics callback

{
     ble : {
        read_characteristic_results : [ 
            {
                address : "abcdef012345",
                service_uuid : "FF00",   //hex string
                characteristic_uuid : "FF01",   //hex string
                data  : [0x00, 0x00, ...],   //data array
            },
            { ... }, ...
        ] 
     }
}

write characteristic

{
     ble : {
        write_characteristic : {
             address : "abcdef012345",  //required. 
             service_uuid :   "FF00",  //required.  
             chracteristic_uuid :  "FF01",  //required. 
             data : [0x00, 0x00, ...],     // write data for data array
        } 
     }
}

write characteristics callback

{
     ble : {
        write_characteristic_results : [ 
            {
                address : "abcdef012345",
                service_uuid : "FF00",   //hex string
                characteristic_uuid : "FF01",   //hex string
                result  : "success",   //success or failed
            },
            { ... }, ...
        ] 
     }
}

error callback

{
     ble : {
        errors : [ 
           {
               error_code : 1,
               message : "ERROR MESSAGE",
               address : "abcdef012345", //hex string or null
               service_uuid : "FF00",           //hex string or null
               characteristic_uuid : "FF01", //hex string or null
            }
            { ... }, ...
        ] 
     }
}

LogicAnalyzer

Monitor io logic level changes by sampling io.

init

{
    logic_analyzer: {
        io: [0], // array of target io. currently only one target available
        interval: 1,  // 1msec interval
        duration: 1000  // 1000msec
    }
}

init with triger filte

triger is optioanl triger configration. without this, logicanalyzer will start with any io level changes. triger specify start position. value measn start value. true/false. samples measn how that values consists. So, With below sample code, you will receive only datas which start with "false, false, false" 3bit.

{
    logic_analyzer: {
        io: [0], // array of target io. currently only one target available
        interval: 1,  // 1msec interval
        duration: 1000  // 1000msec
        triger: {
            value: false,
            samples: 3
        }
    }
}

callback

high bit fast.

{
    logic_analyzer: {
        data: [0, 255, 255]
    }
}

Messaging

send message

{
    message: {
      data: number/string/object/array
      to: [
        "<terget obniz id>"
      ]
    }
}

receive message

{
    message: {
      data: number/string/object/array
      from: string(obniz id) or null.
    }
}

System

reset

{
  system: {
    reset: true
  }
}

self check(circuit IO check)

{
  system: {
    self_check: true
  }
}

wait milliseconds

{
  system: {
    wait: 1000
  }
}

reset obniz when obniz gone to offline.

{
  system: {
    keep_working_at_offline: true/false(default)
  }
}

ws

reset obniz when user websocket disconnected from obnizCloud.

{
    ws: {
        reset_obniz_on_ws_disconnection: true/false(default)
    }
}