thing.bind

The thing.bind command is used to bind a thing to the current session. In this setup there will be a parent Thing to which one or multiple child Things are bound. The child Things are based on the same or different Thing definitions.

When a new Thing connects to the IoT Portal through a parent using thing.bind, the parent makes the Thing look connected to the IoT Portal by sharing the connection session with the Thing(s) connected (bound) to the parent. For more information on Bound Things, see Bound things.

This command requires that the session in use is authenticated as an application using an AppToken.

In the below TR50 Request it allows a new child Thing defined using a Thing definition mydef to be created with a Thing key myThing. The bindTo parameter is optional and it allows a Thing to indirectly bind a child Thing to a different Thing with a Thing key of myparentThing. If the bindTo parameter is not specified, the child Thing is bound to the Thing key of the Thing making the thing.bind request.

TR50 Request

{
  "cmd": {
    "command": "thing.bind",
    "params": {
      "key": "myThing",
      "autoDefKey": "mydef",
      "bindTo": "myparentThing"
    }
  }
}

Request Parameters

Name Type Required Description
key String Yes Identifies the thing to bind to the session.
autoDefKey String Identifies the Thing Definition to use for creating the Thing when it does not already exist.
autoDefThingName String If the thing is auto-defined as a result of the bind, the thing's name will be set to the value specified here, if not specified, the name will be set to "auto:<thingkey>".
autoDefTags String array If the thing is auto-defined as a result of the bind, the specified tags will be added to the thing.
autoDefSecTags String array If the thing is auto-defined as a result of the bind, the specified security tags will be added to the thing.
bindTo String Is a thing key that, If specified, will be used as the parent thing to be bound to. If not specified, the thing will be bound to the thing specified in the current session.

TR50 Response

If the command is sent successfully a success message is returned. Otherwise, an error and error message will be returned.

{
  "cmd": {
    "success": true
  }
}

C API

/ basic API
int tr50_thing_bind(void *tr50, const char *thing_key);
 
// extended API
int tr50_thing_bind_ex(void *tr50, const char *thing_key, void* optional_params, void** optional_reply, char** error_msg);

JAVA API

//Synchronous
int bind(String key, String autoDefKey, Object response);
 
//Asynchronous
int bind(String key, String autoDefKey, DwOpenReceiveActionListener recv, Object response);

Response Objects:  StringReply, DwOpenResponse (Refer JAVA - Worker APIs

When a sensor (Thing key: sensor3) connects to the IoT Portal through a Gateway (using the thing.bind call), the gateway makes the Thing look connected by sharing the connection session with the Thing(s) connected to the gateway. Your property publishes will slightly vary as you will be publishing to the sensor Thing, so the Thing key will need to be specified

{
  "1": {
    "command": "property.publish",
    "params": {
      "thingKey": "sensor3",
      "key": "mygateway",
      "value": "2"
    }
  }
}