Menu
Menu
+
My Panels
Menu
Circus API
Overview
REST JSON commands
Implementations
Arduino
Pure linux
Raspbian
Pure Java
Web pages
Second Life
Overview

We provide a REST specification of well defined commands that allow your things to publish and read signals.

A signal is a changing value and/or location with some additional static information.

Your things will send the commands http commands (GET/PUT/POST/DELETE...)...

... while our platform will respond with JSON formatted data.

In the end your signals will be published for you and/or the community

And you will be be able to manage your signals and others from community in your dashboard

...in scada way

...as a timeline

...or geolocated

Your thing may be implemented with any software/hardware you like.

We have tutorials, examples and libraries for some known platforms that may make it easier. If you made something too, just let us know!

Circus Of Things REST JSON commands
Your account token
These are the commands you need to recursively feed and read dynamic data from signals.
PUT
WriteValue
Refresh the instant value for the signal.
GET
ReadValue
Get the actual value for the signal.
Arduino libraries for Circus.
Name CircusWifiLib 3.0.0
Description Implements ReadValue and WriteValue for any Arduino board connected to an external ESP8266 module.
Download CircusWifiLib3.0.0.zipCircusWifiLib3.0.0.rar
Hardware Arduino board (nano, uno, ...) + external ESP8266 module
Steps:

1) Download the library above (includes examples) and unzip it inside your "libraries" folder of your Arduino IDE.

2) Open a main sketch with your code from where you will make use of the write() and read() functions of the library. You can use ReadOneSignal.ino or WriteOneSignal.ino as good start points for your sketch

3) Place your account token in the variable of your sketch. Also define the variables with your wifi SSID, wifi password and with the key you want to write/read at Circus.

Circus tutorials using Arduino.
Arduino examples at Circus.
Temperature at home
Elisas plant soil moisture level
Rain level in Madrid
Set the commands on your linux
Set environment variable

For the different scripts to work you will need to set up the global environment variable CIRCUSTOKEN which will let the server recognize you as a valid user.

Place it at the end of your /etc/bash.bashrc file, like this:

CIRCUSTOKEN=your_token_here

To find your token, log in, go to up-rigth corner photo and select account.

Get the commands

Follow the next steps to get get the circus commands described above available in your Raspberry.

  • Make a temporary file and get in it
    sudo mkdir ~/temp
    cd ~/temp
  • Get the debian package with all you need from our site
    sudo wget https://circusofthings.com/deb/raspi/CircusRaspiLib.deb
  • Unpack it and let it be installed
    sudo dpkg -i CircusRaspiLib.deb
  • Give permissions to the new files to be executable by your user
    sudo chmod 755 /usr/local/bin/circus*
Available commands for Circus

Once you end with the steps above, these are the available commands in linux:

circusreadvalue [ options ] [ -k SIGNALKEY ]
Options:
-v: verbose

Will read the value of the signal defined by SIGNALKEY and put in stdout
circuswritevalue [ options ] [ -k SIGNALKEY ] [ -n NUMERICVALUE ]
Options:
-v: verbose

Will set the given NUMERICVALUE as the value of the signal defined by SIGNALKEY
Examples

Now you are done, you can use our Circus commands.

Remember when you access your raspi GPIO pins that these have to be set as input/output in accordance with the command you are going to run. For instance, if your are going to write what is shown in a signal in Circus to your GPIO 8 using circussignaltopin command, GPIO 8 has to be set as an output

Setting GPIOs as input/output from command line is clearly described here

But, you can also use the -F option from commands. In that case, you should run them preceeded by sudo -E

Example: Reading a signal value

Just read the temperature in Celsius degrees in Madrid, as we have a device feeding the signal with key 943874351

pi@raspberry:~ $ circusreadsignal -k 943874351
18
Example: Posting some value on a signal at Circus

I use it to post my deposit desired level on 110cm at the signal with key=137572561 and my pump controller will read it there to fix it

pi@raspberry:~ $ circuswritesignal -k 137572561 -n 110
Set the commands on your linux
Set environment variable

For the different scripts to work you will need to set up the global environment variable CIRCUSTOKEN which will let the server recognize you as a valid user.

Place it at the end of your /etc/bash.bashrc file, like this:

CIRCUSTOKEN=your_token_here

To find your token, log in, go to up-rigth corner photo and select account.

Get the commands

Follow the next steps to get get the circus commands described above available in your Raspberry.

  • Make a temporary file and get in it
    sudo mkdir ~/temp
    cd ~/temp
  • Get the debian package with all you need from our site
    sudo wget https://circusofthings.com/deb/raspi/CircusRaspiLib.deb
  • Unpack it and let it be installed
    sudo dpkg -i CircusRaspiLib.deb
  • Give permissions to the new files to be executable by your user
    sudo chmod 755 /usr/local/bin/circus*
Available commands for Circus

Once you end with the steps above, these are the available commands in linux:

circusreadvalue [ options ] [ -k SIGNALKEY ]
Options:
-v: verbose

Will read the value of the signal defined by SIGNALKEY and put in stdout
circuswritevalue [ options ] [ -k SIGNALKEY ] [ -n NUMERICVALUE ]
Options:
-v: verbose

Will set the given NUMERICVALUE as the value of the signal defined by SIGNALKEY
circussignaltopin [ options ] [ -k SIGNALKEY ] [ -p GPIONUMBER ]

Options:
-v: verbose
-h: help
-F: force port direction if not correctly set
-r: maximum number of retries for the case in which server value can't be reached

Recursively will set the value read from the input GPIO defined by GPIONUMBER as the value of the signal defined by SIGNALKEY.
circuspintosignal [ options ] [ -k SIGNALKEY ] [ -p GPIONUMBER ]

Options:
-v: verbose
-h: help
-F: force port direction if not correctly set
-r: maximum number of retries for the case in which server value can't be reached

Recursively will set the value of the signal defined by SIGNALKEY ras the outputvalue at the GPIO defined by GPIONUMBER
Will refuse to put values different form '1' or '0' on the digital output.
Examples

Now you are done, you can use our Circus commands.

Remember when you access your raspi GPIO pins that these have to be set as input/output in accordance with the command you are going to run. For instance, if your are going to write what is shown in a signal in Circus to your GPIO 8 using circussignaltopin command, GPIO 8 has to be set as an output

Setting GPIOs as input/output from command line is clearly described here

But, you can also use the -F option from commands. In that case, you should run them preceeded by sudo -E

Example: Reading a signal value

Just read the temperature in Celsius degrees in Madrid, as we have a device feeding the signal with key 943874351

pi@raspberry:~ $ circusreadsignal -k 943874351
18
Example: Posting some value on a signal at Circus

I use it to post my deposit desired level on 110cm at the signal with key=137572561 and my pump controller will read it there to fix it

pi@raspberry:~ $ circuswritesignal -k 137572561 -n 110
Example: Binding from a Circus signal to a local GPIO pin

Will show wheter is raining or not in Madrid flashing a led in my local GPIO 6. Note that -F option will force GPIO 6 to be an output.

pi@raspberry:~ $ sudo -E circussignaltopin -v -F -k 830339759 -p 6
cat: /sys/class/gpio/gpio6/direction: File does not exist
GPIO port 6 is not set as an output
Forcing GPIO as an output, as -F option was selected
Attempting to bind signal at circusofthings.com to your pin -GPIO: 6- in your Respberry
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]

Now, we try just the same but setting port mannually

pi@raspberry:~ $ sudo echo "6" > /sys/class/gpio/export
pi@raspberry:~ $ sudo echo "out" > /sys/class/gpio/gpio6/direction
pi@raspberry:~ $ circussignaltopin -v -k 830339759 -p 6

GPIO port 6 is an output. Ok
Attempting to bind signal at circusofthings.com to your pin -GPIO: 6- in your Respberry
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
[ Read from Key: 830339759 ] 0 -> [ GPIO 6 ]
Example: Binding from local GPIO pin to a Circus signal

This is the code I use to feed my signal Is it rainning in Algaida? from the open/closed contact of my rain sensor connected to my Raspberry on GPIO 4

pi@reconada-pi-1:~ $ circuspintosignal -v -k 16320557 -p 4
GPIO port 4 is an input. Ok
Attempting to bind signal -key: 16320557- at circusofthings.com to your pin -GPIO: 4- in your Respberry
[ Read from GPIO 4 ] 0 -> [ Signal Key: 16320557 ]
[ Read from GPIO 4 ] 0 -> [ Signal Key: 16320557 ]
[ Read from GPIO 4 ] 0 -> [ Signal Key: 16320557 ]
[ Read from GPIO 4 ] 0 -> [ Signal Key: 16320557 ]
Java libraries for Circus.
Name CircusLib.1.1.0.java
Description Implements ReadValue and WriteValue in java language.
Download source code: CircusLib.java
Download jar file: circusofthings.com.jar
Download utils: jaumemirallesisern-gps.jar
Java specification
CircusLib
com.circusofthings.api.ver110

Class CircusLib

  • java.lang.Object
    • com.circusofthings.api.ver110.CircusLib


  • public class CircusLib
    extends java.lang.Object
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.lang.String VERSION 
    • Constructor Summary

      Constructors 
      Constructor and Description
      CircusLib(java.lang.String token) 
    • Constructor Detail

      • CircusLib

        public CircusLib(java.lang.String token)
        Parameters:
        token - Is the token provided in your account to get access to the api server.
    • Method Detail

      • writeValue

        public JSONObject writeValue(java.lang.String key,
                                     double value,
                                     double lat,
                                     double lon,
                                     double alt)
        Parameters:
        key - The key of the signal to be feeded.
        value - The value to be actually written as the current output.
        lat - The latitude value to be set
        lon - The longitude value to be set
        alt - The altitude value to be set
        Returns:
        An org.json.JSONObject will be returned.
        String Status = Status code of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Status").
        String Message = Status message of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Message").
        Possible status / messages
        200 = Success.
        400 = The syntax of the query is wrong.
        401 = The API token is unknown or no longer available.
        403 = Insuficient permissions to write this signal.
        404 = Signal key not found.
      • writeValue

        public JSONObject writeValue(java.lang.String key,
                                     double lat,
                                     double lon,
                                     double alt)
        Parameters:
        key - The key of the signal to be feeded.
        lat - The latitude value to be set
        lon - The longitude value to be set
        alt - The altitude value to be set
        Returns:
        An org.json.JSONObject will be returned.
        String Status = Status code of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Status").
        String Message = Status message of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Message").
        Possible status / messages
        200 = Success.
        400 = The syntax of the query is wrong.
        401 = The API token is unknown or no longer available.
        403 = Insuficient permissions to write this signal.
        404 = Signal key not found.
      • writeValue

        public JSONObject writeValue(java.lang.String key,
                                     double value)
        Parameters:
        key - The key of the signal to be feeded.
        value - The value to be actually written as the current output.
        Returns:
        An org.json.JSONObject will be returned.
        String Status = Status code of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Status").
        String Message = Status message of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Message").
        Possible status / messages
        200 = Success.
        400 = The syntax of the query is wrong.
        401 = The API token is unknown or no longer available.
        403 = Insuficient permissions to write this signal.
        404 = Signal key not found.
      • readValue

        public JSONObject readValue(java.lang.String key)
        Parameters:
        key - The key of the signal to be checked.
        Returns:
        An org.json.JSONObject will be returned.
        String Status = Status code of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Status").
        String Message = Status message of the response given by the Circus Server. Get the value using: (org.json.JSONObject).getString("Message").
        String Value = Current value (double) for the signal. Get the value using: (org.json.JSONObject).getString("Value").
        Possible status / messages
        200 = Success.
        400 = The syntax of the query is wrong.
        403 = Insuficient permissions to read this signal.
        404 = Signal key not found.
Java examples

I made a class named IncreasingValue which is used to feed the Increasing value posted at Circus for test purposes.

package com.circusofthings.examples.javaclient;

import com.circusofthings.api.ver110.CircusLib;
import org.json.JSONObject;

public class IncreasingValue extends Thread
{
    private final String key;
    private final String token;
    private static final long FREC = 20000L;

    public IncreasingValue(String key, String token)
    {
      this.key = key;
      this.token = token;
    }

    public void run()
    {
        CircusLib commands = new CircusLib(token);
        double value = 0;
        for (;;) {
            value++;
            if(value>1000){value=0;}
            JSONObject json = commands.writeValue(key, value);
            System.out.println(json.toString());
            try {
                Thread.sleep(FREC);
            } catch (InterruptedException ex) {
                Thread.currentThread().interrupt();
            }
        }
    }
}
                

It can be run adding this two lines in your code:

IncreasingValue increasingValue = new IncreasingValue("3456", "your_token_here");
increasingValue.start();
Javascript libraries for Circus.
Name CircusLib.js
Description The CircusLib.js implements the circusofthings.com API for embedding signals in a web.
Download CircusLib.js
Steps:

Note! Only public signals can be embeded in a web (no token is needed).

1) Invoke the downloaded circuslib.js script (right before closing BODY tag). Do the same with jquery lib:

<script type="text/javascript" src="/your/realtive/path/circuslib.js"></script>
<script type="text/javascript" src="/your/realtive/path/jquery-3.1.0.js"></script>

2) Place this DIV in your HTML code, one for each signal to show, pasting key where asked, like this:

    <div class='circus' id='your_key_here'>
        <div class='value'>
            <!--VALUE will be placed here-->
        </div>
        <div class='location' style='display:none'>
            <div class='loclabel'>Latitude: </div><div class='lat locelement'><!--LAT will be placed here--></div>
            <div class='loclabel'>Longitude: </div><div class='lon locelement'><!--LON will be placed here--></div>
            <div class='loclabel'>Altitude: </div><div class='alt locelement'><!--ALT will be placed here--></div>
            <div class='loclabel'>Is moving: </div><div class='ismobile locelement'><!--ISMOBILE will be placed here--></div>
        </div>
    </div>
                

Note: if location is set to style='display:none' this div won't show and no queries about location will be done in order to free browser's load. Turn it to style='display:block' to work

3) Invoke function pollCircus() once. For instance, when your page loads, in the BODY tag:

<body onload="pollCircus()"> <!--will read every 2 seconds-->

optional) Give it some style, include this css file in your header

<link href="/your/relative/path/example_js.css" rel="stylesheet">

Of course, it's just an idea... feel free to change it

Examples.

In the example example_js_randomsignal there is displayed a single value from the signal Random Signal ignoring any location data (style='display:none')

In the example example_js_madridtemp there is displayed a temperature from the signal Temperature in Madrid reading location data (style='display:block')









You can send data within or from Second Life and connect it to your real life gadgets and apps.

It can be done fast with some ready-to-use scripted objects you can get in the Marketplace.

Or you can make your own objects inside SL using its LSL language to communicate.

Existing objects inside SL

A sample of this object can be used in our parcel.

This Transmitter object will send from SL signals to circusofthings.com.
circusofthings.com is a platform where the values of sensors from RL, or values from apps or metaverses can be published or read. This means it may let you connect physical devices (Arduino, Raspberry or any kind) among them, or with second life or with a web. The possibilities are infinite. So, use this transmitter to send a signal defined by a "key" that is published in circusofthings.com. You will need a valid account there to have a "token" that identifies you. (When you want to read values at Circus rather than feeding it, use our available "Circus_Receiver")
------------------------------------------
Usage
------------------------------------------
Touch the device to get the main menu.
Press "configure" to set the proper params.
You will see the parameters as they actually are set.
"KEY" identifies the signal published at Circus that you want to feed/write.
"TXCHANNEL" is the local channel in SL where the transmitter will listen for a pair key/value to post at Circus.
"RESPONSECHANNEL" is the local channel in SL where the server response will be shown.
Set any of the above params pressing its button.
PLEASE REMEMBER: To set a valid token provided in the account at circusofthings.com.
You or your scripted object has to write on TXCHANNEL: [key_of_target_signal] [space_character] [float_value_to_post_at_signal]
for instance: "23780 100" (without quotes), means "write value 100 for signal published at Circus identified by key 23780"
------------------------------------------
Goal
------------------------------------------
Type or send from objects values from SL to RL.
This receiver object will get in SL the signals from circusofthings.com.
circusofthings.com is a platform where the values of sensors from RL, or values from apps or metaverses can be published or read. This means it may let you connect physical devices (Arduino, Raspberry or any kind) among them, or with second life or with a web. The possibilities are infinite. So, use this receiver to read a signal defined by a "key" that is published in circusofthings.com. You will need a valid account there to have a "token" that identifies you. (When you want to publish/change values at Circus rather than reading it, use our available "Circus_Transmitter")
------------------------------------------
Usage
------------------------------------------
Touch the device to get the main menu.
Press "configure" to set the proper params.
You will see the parameters as they actually are set.
"KEY" identifies the signal published at Circus that you want to read.
"VALUECHANNEL" is the local channel in SL where the read value will be broadcasted.
"LABELCHANNEL" is the local channel in SL where the label of signal defined by the publisher will be broadcasted.
"UNITSCHANNEL" is the local channel in SL where the units of signal defined by the publisher will be broadcasted.
"DESCRIPTIONCHANNEL" is the local channel in SL where the description of signal defined by the publisher will be broadcasted.
"Refresh rate": Defined in seconds. Is the period of each scan for a new Value at Circus. It can't be less than 5 seconds. You may to make it bigger to optimize lag in your parcel.
Set any of the above params pressing its button.
PLEASE REMEMBER: To set a valid token provided in the account at circusofthings.com.
------------------------------------------
Goal
------------------------------------------
Use the broadcasted value from RL to trigger actions on other objects in SL.
For instance, you can use a "Circus_Monitor" to display the values in RL.
This Monitor object will display what is broadcast from a "Circus_receiver" that is getting info from circusofthings.com.
circusofthings.com is a platform where the values of sensors from RL, or values from apps or metaverses can be published or read. This means it may let you connect physical devices (Arduino, Raspberry or any kind) among them, or with second life or with a web. The possibilities are infinite. So, use this monitor to display what is heard from the channels you set.
Note: It can be used as a universal monitor if you or your object sends the messages to be displayed in proper channels. Hovewer the length and layout is strongly designed to use with a a "Circus_Receiver"
------------------------------------------
Usage
------------------------------------------
Touch the device to get the main menu.
You will see the parameters as they actually are set.
"KEY" identifies the signal published at Circus that you want to read.
"VALUECHANNEL" is the local channel in SL where the read value will be heard.
"LABELCHANNEL" is the local channel in SL where the label of signal defined by the publisher will be heard.
"UNITSCHANNEL" is the local channel in SL where the units of signal defined by the publisher will be heard.
"DESCRIPTIONCHANNEL" is the local channel in SL where the description of signal defined by the publisher will be heard.
Set any of the above params pressing its button.
Press "Signal info" to get the received description from publisher for this signal.
------------------------------------------
Goal
------------------------------------------
Use the "Circus_Monitor" to display what the "Circus_receiver" gets from RL