Technology Careers Contact
Documentation Community Download Support

JSON API

The JSON formated data is very common and widely used by many programming languages. Luos allows you to convert low-level Luos information into JSON objects, enabling conventional programming languages to easily interact with your device.
To do that, you must add a specific app module called Gate on your device.

The Gate module is an app that converts Luos messages from a device's network into JSON data format, and the other way from JSON to Luos messages.
The Gate module can be hosted into different kinds of nodesHardware element (MCU) hosting and running Luos and hosting one or several modules. allowing you to choose the communication way fitting with your project (USB, Wifi, Bluetooth, etc.)

Warning: The Gate module refreshes sensors information as fast as it can, so that can be intensive to Luos bandwidth.

How to start using the JSON API

Before using your device through JSON, you have to be connected to the communication flow depending on the node type hosting your Gate module.
Then you can start the Gate by sending:

{"detection": {}}\r

This command asks the Gate to start a topological detection, create a routing table, convert it into JSON and send it back to you.

Routing table messages

Warning: Make sure to read and understand how routing table works before reading this part.

After the Gate starts, the first message you receive is a routing table.
This first message is really important, because it contains all the information allowing you to create a code object for your device, containing all its features.

Routing table structure

A routing table in JSON consists in a list of the nodes present in the Luos network:

{
   "route_table":[
      {
         // node 1
      },
      {
         // node 2
      },
      {
         // node 3
      }
      // ...
   ]
}

Nodes information

Each listed node of the network has basic node information and a list of hosted modules:

{ // node 1
   "uuid":[1, 2, 3],
   "port_table":[1, 2],
   "modules":[
      {
         // module 1
      },
      {
         // module 2
      }
      // ...
   ]
}

Note: To understand the meanings of uuid and port_table, please refer to the routing table page.

Modules

Each listed module of a node has basics modules information:

{ // module 1
   "type":"Type",
   "id":1,
   "alias":"Alias"
}

Note: To understand the meanings of type, id and alias, please refer to the module page.

Full routing table example

{
   "route_table":[
      {
         "uuid":[2031684, 1112756496, 540423216],
         "port_table":[2, 65535],
         "modules":[
            {
               "type":"Gate",
               "id":1,
               "alias":"r_right_arm"
            }
         ]
      },
      {
         "uuid":[4915239, 1194612503, 540554032],
         "port_table":[4, 1],
         "modules":[
            {
               "type":"State",
               "id":2,
               "alias":"lock"
            },
            {
               "type":"Unknown",
               "id":3,
               "alias":"start_control"
            }
         ]
      },
      {
         "uuid":[2818086, 1194612503, 540554032],
         "port_table":[5, 3],
         "modules":[
            {
               "type":"Imu",
               "id":4,
               "alias":"gps"
            }
         ]
      },
      {
         "uuid":[2097186, 1194612503, 540554032],
         "port_table":[65535, 4],
         "modules":[
            {
               "type":"Color",
               "id":5,
               "alias":"alarm"
            },
            {
               "type":"Unknown",
               "id":6,
               "alias":"alarm_control"
            }
         ]
      }
   ]
}

Below is a visual representation of this routing table:

Module's information messages

When the JSON routing table is transmitted, the Gate starts to update and stream your network data with modules information.

This JSON is a "module" object listing all the modules by their alias and the values they send:

{
   "modules":{
      "module_alias1":{
         "value1":12.5
      },
      "module_alias2":{
         "value1":13.6,
         "value2":[1, 2, 3, 4]
      }
   }
}

You can use the exact same JSON object structure to send data to modules.

Here is the list of all values that can be used by modules:

Value nameDefinition
power_ratioPercentage of power of an actuator (-100% to 100%)
target_rot_positionActuator's target angular position (can be a number or an array)
limit_rot_positionActuator's limit angular position
limit_trans_positionActuator's limit angular position
limit_powerLimit ratio of an actuator's reduction
limit_currentLimit current value
target_rot_speedActuator's target rotation speed
target_trans_positionActuator's target linear position (can be a number or an array)
target_trans_speedActuator's target linear speed
timeTime value
compliantActuator's compliance status
pidSet of PID values (proportionnal, integral, derivative)
resolutionSensor's resolution value
offsetOffset value
reductionRatio of an actuator's reduction
dimensionDimension value
voltVoltage value
currentElectric current value
reinitReinitialisation command
controlControl command (play, pause, stop, rec)
colorColor value
io_stateIO state
ledBoard's LED
node_temperatureNode's temperature
node_voltageNode's voltage
uuidModule's uuid
renameRenaming an alias
revisionFirmware revision
trans_positionTranslation position value
trans_speedTranslation speed value
rot_positionRotation position value
rot_speedRotation speed value
luxLux (light intensity) value
temperatureTemperature value
forceForce value
momentTorque value
powerPower value
linear_accelLinear acceleration value
gravity_vectorGravity vector value
compassCompass value
gyroGyroscope value
accelAcceleration value
eulerEuler angle value
quaternionQuaternion values
rotational_matrixRotational matrix values
headingHeading
pedometerSteps number value
walk_timeWalk time value
luos_revisionluos's version
robus_revisionrobus's version

Here is an exemple of a message sent by a Potentiometer module about the rotation angle of the associated potentiometer:

{
   "modules":{
      "potentiometer_m":{
         "rot_position":12.5
      }
   }
}

Custom parameters and specific messages

Some messages are specifically handled:

Custom parameters can be defined and sent to modules through the JSON API, either with Python (Pyluos) or any other programming language on a computer side. Here is an example of a C function that can be implemented in order to send commands to modules in a Luos Network, through a gate:

def sendCmd(s, cmd, sleep_time=0.5):
    cmd = cmd + '\r'
    print(cmd)
    s.write(cmd.encode())
    time.sleep(sleep_time)
s = serial.Serial(sys.argv[1], 1000000)
# detect Luos network
sendCmd(s, '{"detection": {}}')
# set speed mode and compliant mode
sendCmd(s, '{"modules": {"controlled_moto": {"parameters": 2441}}}')
# set pid parameters
sendCmd(s, '{"modules": {"controlled_moto": { "pid": [20, 0.02, 90]}}}')
# set speed mode and non compliant mode
sendCmd(s, '{"modules": {"controlled_moto": {"parameters": 2440}}}')

Parameters are defined by a 16-bit bitfield.

ObjectDefinitionStructureModule(s)
parametersenabling or disabling some measurementLink to structure (GitHub)Stepper, Controlled-motor, Servo
parametersenabling or disabling some measurementLink to structure (GitHub)Imu

Other specific messages:

ObjectDefinitionModule(s)
registerMotor memory register filed with [register_number, value]Dynamixel, void
set_idA set id commandDynamixel, void
wheel_modeThe wheel mode parameter for Dynamixel servomotors True or FalseDynamixel, void
delayreduce modules refresh rateGate

Module exclusion messages

Module can be excluded of the network if a problem occurs (See message handling for more information). In this case, the Gate sends an exclusion message indicating that this module is no longer available:

{"dead_module": "module_alias"}

Sending large binary data

Binary data such as, for example, a motor tarjectory can't be included into a Json file if it is too large. In order to allow this type of transmission, the size of the binary data is sent through the Json, then followed by the actual data in binary format.

  • If the data is short, it can be displayed inside the JSON as a regular value (see the different values in Module's information messages section), or as a table of several values (for example a motor trajectory).

  • If the data is large, the defined value must be a table of one element, containing only the size of the binary data to be transfered, in bytes.

The following example shows a transfert of a binary data of 1024 bytes.

{
   "modules":{
      "module_alias1":{
         "rot_position":[1024]
      }
   }
}
###BINARY_DATA###

Follow Watch Star

Luos is constantly evolving! Keep in touch to follow the last updates: