Skip to content

External Service API

Jump to bottom
Hyunseok edited this page Apr 20, 2026 · 12 revisions

Simulation control

CLOiSim supports web-based simulation control service through websocket as an external interface.

default service port is 8080, but you can change service port setting environment variable

export CLOISIM_SERVICE_PORT=8080

websocket service path: ws://127.0.0.1:8080/{service-name}

Just send a request data as a JSON format.

Supporting Service Name

  • control => url: ws://127.0.0.1:8080/control

    • Reset simulation

      • {"command": "reset"}

    • Get device list

      • {"command": "device_list"}
      • options:
        • filter: 
          {"command": "device_list", "filter": "CLOi"}
        • indenting JSON format: 
          {"command": "device_list", "indent": false}
        • example: 
          {"command": "device_list", "filter": "CLOi", "indent": false}

    • Get topic list

      • since CLOiSim-4.14.1 
        {"command": "port_list"}
      • but, before CLOiSim-4.14.1 
        {"command": "topic_list"}
      • options:
        • filter: 
          {"command": "port_list", "filter": "CLOi"}
        • indenting JSON format: 
          {"command": "port_list", "indent": false}
        • example: 
          {"command": "port_list", "filter": "CLOi", "indent": false}

    • Start recording since CLOiSim-4.14.1

      • {
  "command": "start_record", 
  "filename": "capture_simulation"
}

    • Stop recording since CLOiSim-4.14.1

      • {"command": "stop_record"}

    • Get target model information since CLOiSim-5.1.0

      • {"command": "get_model_info", "target_model": "my_robot"}

      • will get response

        {
  "command":"get_model_info",
  "result": {
    "name": "NR",
    "pose": {
      "position": {"x": 0.0, "y": 0.0, "z": 0.0},
      "orientation": {"roll": 0.0, "pitch": 0.0, "yaw": 0.0}
    }
  }
}

    • Teleport specific model since CLOiSim-5.1.0

      • {
  "command": "teleport",
  "world_reset": true, // same as Reset simulation
  "targets": [
    {
      "target": "model_name",
      "reset": true, // reset only specific target model
      "pose": {
        "x": 222,
        "y": 111,
        "z": 0.1,
        "roll": 0,
        "pitch": 0, 
        "yaw": 0
      }
    },
    {
      "target": "model_name2",
      "reset": false,
      "pose": {...}
    }
  ]
}

  • markers => url: ws://127.0.0.1:8080/markers

    • Markers are consist of group, id, type, color.

      • id must be unique in group.
      • Check supporting color type in below
        • Red, Green, Blue, Gray, Orange, Lime, Pink, Purple, Navy, Aqua, Cyan, Magenta, Yellow, Black
      • There are four types of 'type'. Must describe type properties for each type.
        • line
          • "line":{"size":0.03, "point":{"x":1.1, "y":1.1, "z":3.3}, "endpoint":{"x":1.1, "y":1.1, "z":10.0}}}
        • text
          • "text":{"size": 5, "align": "center", "following": null, "text": "Hello!!!!\nCLOiSim!!", "point": {"x": 1.0, "y": 1.0, "z": 4.0}}
        • sphere
          • "sphere":{"size":0.1, "point":{"x": 1.1, "y": 2.2, "z": 4.1}}
        • box
          • "box":{"size": 0.2, "point":{"x": 2.1, "y": 3.2, "z": 4.1}}

    • Examples

      • Adding markers command format

        • {"command":"add", "markers":[{"group":"sample","id":4,"type":"`type what you want`","color":"red", `Describe 'type properties' here`}]}

      • Add markers (line type)

        • {"command":"add", "markers":[{"group":"sample","id":4,"type":"line","color":"red", "line":{"size":0.03, "point":{"x":1.1, "y":1.1, "z":3.3}, "endpoint":{"x":1.1, "y":1.1, "z":10.0}}},]}

      • Modify markers

        • {"command":"modify", "markers":[{"group":"sample", "id":4, "type":"line", "color":"blue", "line":{"size":0.05, "point":{"x":1.1, "y":1.1, "z":3.3}, "endpoint":{"x":1.1,"y":1.1,"z":5.0}}},]}

      • Remove markers ```

        • {"command": "remove", "markers":[{"group":"sample","id":5,"type":"line"},]}

      • Get markers list

        • {"command": "list"}`
        • {"command": "list", "filter":{"group": "sample"}}

    • 'Following object feature' in 'Text' marker

      • Enable following function
        • Input target object name in simulation on "following" field.
        • "text":{"size": 5, "align": "center", "following": "CLOI_Porter_Robot", "text": "Hello, CLOiSim!!", "point": {"x": 1.0, "y": 3.0, "z": 4.0}}
      • Disable following function
        • "text":{"size": 5, "align": "center", "following": "", "text": "Hello, CLOiSim", "point": {"x": 1.0, "y": 3.0, "z": 4.0}}
        • "text":{"size": 5, "align": "center", "following": null, "text": "Hello, CLOiSim", "point": {"x": 1.0, "y": 3.0, "z": 4.0}}

Examples

markers

> {"command":"add","markers":[{"group":"sample","id":4,"type":"text","color":"red","text":{"size":5,"align":"center","following":"cloi1","text":"Hello!!!!\nCLOiSim!!","point":{"x":1.0,"y":1.0,"z":4.0}}}]}
< {
  "command": "add",
  "result": "ok",
  "lines": null,
  "texts": null,
  "boxes": null,
  "spheres": null
}

control

cloi2_ws$ wsdump.py ws://127.0.0.1:8080/control

> {"command": "reset"}
< {
  "command": "reset",
  "result": "ok"
}

> {"command": "device_list", filter:"cloi1", indent:true}
< {
  "command": "device_list",
  "result": {
    "cloi1": {
      "MULTICAMERA": {
        "multi_camera": {
          "Info": 49154,
          "Data": 49155
        }
      },
      "CAMERA": {
        "camera": {
          "Info": 49156,
          "Data": 49157
        }
      },
      "DEPTHCAMERA": {
        "depthcamera": {
          "Info": 49158,
          "Data": 49159
        }
      },
      "REALSENSE": {
        "realsense": {
          "Info": 49160,
          "colorInfo": 49168,
          "colorData": 49169,
          "ir1Info": 49170,
          "ir1Data": 49171,
          "ir2Info": 49172,
          "ir2Data": 49173,
          "depthInfo": 49174,
          "depthData": 49175
        }
      },
      "LASER": {
        "lidar": {
          "Info": 49161,
          "Data": 49162
        }
      },
      "GPS": {
        "gps": {
          "Info": 49163,
          "Data": 49164
        }
      }
    }
  }

> {"command":"port_list"}
< {
  "command":"port_list",
  "result":{"WorldUnityRosClock":49152,"SeochoTowerElevatorSystemControl":49153,"cloi1multi_cameraInfo":49154,"cloi1multi_cameraData":49155,"cloi1cameraInfo":49156,"cloi1cameraData":49157,"cloi1depthcameraInfo":49158,"cloi1depthcameraData":49159,"cloi1realsenseInfo":49160,"cloi1lidarInfo":49161,"cloi1lidarData":49162,"cloi1gpsInfo":49163,"cloi1gpsData":49164,"cloi1RobotControlInfo":49165,"cloi1RobotControlTx":49166,"cloi1RobotControlRx":49167,"cloi1realsensecolorInfo":49168,"cloi1realsensecolorData":49169,"cloi1realsenseir1Info":49170,"cloi1realsenseir1Data":49171,"cloi1realsenseir2Info":49172,"cloi1realsenseir2Data":49173,"cloi1realsensedepthInfo":49174,"cloi1realsensedepthData":49175}}

Copyright © 2020 LG Electronics Inc.

Build guide is only for developer.

Clone this wiki locally