Thing
Thing component is responsible for all of the commands that are related to User’s connected physical device management.
Thing Association
Associate a new thing
Associate a hardware Thing to the currently logged-in user. Thing association describes ownership of the physical hardware connected device.
💡 It is recommended to check if thing can be associated before associating new thing.
Result model - Thing
ThingStatusesLastSeen- The last time the device was connected.ReportedStatuses- A list ofThingReportedStatuseach status object should contain.Time- Date and time value representing in which point in time this status was created (On iOS will be represented asTimeStampsince 1970, on android aDateobject).
Name- name of the status. E.g.battery_status.Value- value of the status asString.
💡 Use the
ReportedStatusesto send hardware Thing status to Copilot.cx Admin dashboard and reports. Some examples of such settings might bebattery_status,hardware_status,wifi_module_statusetc.ThingInfo- Containing the following properties: (The values can be updated using the update thing command - please refer update thing section)PhysicalId- The unique ID for a single hardware Thing. Can be the hardware product’s MAC address, or a unique serial number that remains fixed and constant. Usually we use the serial number of the device which is unique.Firmware- The firmware version published by your hardware device.Model- The model of a specific hardware Thing, for example its hardware type or revision, often used to differentiate between products in your product line or different SKUs of your hardware product.
💡
modelvalue can’t be updated once set.CustomSettings- Custom settings for a given hardware Thing. Custom settings can be used as a storage of simple key-value pairs. Those values can be retrieved by the fetch thing command (please refer the relevant section). Custom settings supports the following data types:Name- Specific alias (String) provided by the end-user for a specific hardware Thing.- Primitive data types: Boolean, String, Integer, Float, Double,
- Array of primitive or custom objects.
- Dictionary of primitive or custom objects.
💡 Setting a custom setting value can be chained - meaning using one command call you can set multiple custom setting values. Please refer update thing details.
💡 In order to remove custom setting use
removeCustomValue("KeyToRemove")method.💡 Thing settings can be used for thing preferences or device properties like setting last location of the device, currently selected operation mode and more.
Result error - AssociateThingError
Below are the possibles errors you can receive:
ThingAlreadyAssociated- Physical thing ID already associated.ThingNotAllowed- Logged in user cannot perform the associate operation on this physical thing ID. Please check if thing can be associated using thecheckIfCanAssociatecommand.InvalidParameters- One or more of provided parameters is missing or invalid.RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.associateThing(withPhysicalId: "physicalId", firmware: "firmware", model: "model")
.build()
.execute { (response) in
switch response {
case .success(let thing):
break
case .failure(error: let associateError):
switch(associateError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .invalidParameters(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
case .thingAlreadyAssociated(let debugMessage):
break
case .thingNotAllowed(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.Thing
.associateThing("physicalId", "firmware", "model")
.build()
.execute(new RequestListener<ThingModel, AssociateThingError>() {
@Override
public void success(ThingModel response) {
}
@Override
public void error(AssociateThingError error) {
switch (error) {
case ThingAlreadyAssociated:
break;
case ThingNotAllowed:
break;
case InvalidParameters:
break;
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.Thing
.associateThing("physicalId", "firmware", "model")
.build()
.execute(object : RequestListener<ThingModel?, AssociateThingError?> {
override fun success(response: ThingModel?) {}
override fun error(error: AssociateThingError?) {
when (error) {
AssociateThingError.ThingAlreadyAssociated -> {}
AssociateThingError.ThingNotAllowed -> {}
AssociateThingError.InvalidParameters -> {}
AssociateThingError.RequiresRelogin -> {}
AssociateThingError.ConnectivityError -> {}
AssociateThingError.GeneralError -> {}
}
}
})
Disassociate thing
Disassociate a hardware thing from the currently logged-in user. Thing disassociation breaks the ownership and the connection of the physical hardware connected device and the user.
Result model - Void
Result error - DisassociateThingError
InvalidParameters- One or more of provided parameters is missing or invalid.ThingNotFound- The requested thing physical ID cannot be found.RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.disassociateThing(withPhysicalId: "ConnectedSupermanCape17")
.build()
.execute { (response) in
switch response {
case .success():
break
case .failure(error: let disassociateError):
switch(disassociateError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .invalidParameters(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
case .thingNotFound(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.Thing
.disassociateThing("ConnectedSupermanCape17")
.build()
.execute(new RequestListener<Void, DisassociateThingError>() {
@Override
public void success(Void response) {
// Thing was disassociated successfully
}
@Override
public void error(DisassociateThingError error) {
switch (error) {
case InvalidParameters:
break;
case ThingNotFound:
break;
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.Thing
.disassociateThing("ConnectedSupermanCape17")
.build()
.execute(object : RequestListener<Void?, DisassociateThingError?> {
override fun success(response: Void?) {
// Thing was disassociated successfully
}
override fun error(error: DisassociateThingError?) {
when (error) {
DisassociateThingError.InvalidParameters -> {}
DisassociateThingError.ThingNotFound -> {}
DisassociateThingError.RequiresRelogin -> {}
DisassociateThingError.ConnectivityError -> {}
DisassociateThingError.GeneralError -> {}
}
}
})
Check if thing can be associated
Use the checkIfCanAssociate command in order to validate that the thing can be associated to this specific user. Should happen prior calling the associate command in order to help the user to understand if there's a problem associating this thing.
Result model - CanAssociate
isAssociationApproved-booleanvalue indicating weather a thing can be associated.[RejectReason]- Array of rejection reasons. Reasons can be:ThingAlreadyAssociated- Thing already associated to another user and system does not allow thing association to multiple users simultaneously.ThingNotAllowed- One of the thing parameters does not allow association.Unknown- Thing cannot be associated due to unknown reason.
Result error - CanAssociateThingError
InvalidParameters- One or more of provided parameters is missing or invalid.RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.checkIfCanAssociate(withPhysicalId: "ConnectedSupermanCape17")
.build()
.execute { (response) in
switch response {
case .success(let checkIfCanAssociateResponse):
break
case .failure(error: let checkIfCanAssociateeError):
switch(checkIfCanAssociateeError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .invalidParameters(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.Thing
.checkIfCanAssociate("ConnectedSupermanCape17")
.build()
.execute(new RequestListener<CanAssociateModel, CanAssociateThingError>() {
@Override
public void success(CanAssociateModel response) {
// Check here if the thing can be associated or not.
}
@Override
public void error(CanAssociateThingError error) {
switch (error) {
case InvalidParameters:
break;
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.Thing
.checkIfCanAssociate("ConnectedSupermanCape17")
.build()
.execute(object : RequestListener<CanAssociateModel?, CanAssociateThingError?> {
override fun success(response: CanAssociateModel?) {
// Check here if the thing can be associated or not.
}
override fun error(error: CanAssociateThingError?) {
when (error) {
CanAssociateThingError.InvalidParameters -> {}
CanAssociateThingError.RequiresRelogin -> {}
CanAssociateThingError.ConnectivityError -> {}
CanAssociateThingError.GeneralError -> {}
}
}
})
Fetching things
Fetch user’s associated things
Use fetchThings in order to get a list of the hardware Things associated with the logged in user.
Result model - Array of Thing elements
The result is a list of instances of Thing. Please refer the Thing entity
Result error - FetchThingsError
RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.fetchThings()
.build()
.execute { (response) in
switch response {
case .success(let things):
break
case .failure(error: let fetchError):
switch(fetchError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.Thing
.fetchThings()
.build()
.execute(new RequestListener<List<ThingModel>, FetchThingsError>() {
@Override
public void success(List<ThingModel> response) {
//Fetched the things associated with the user
}
@Override
public void error(FetchThingsError error) {
switch (error) {
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.Thing
.fetchThings()
.build()
.execute(object : RequestListener<List<ThingModel?>?, FetchThingsError?> {
override fun success(response: List<ThingModel?>?) {
//Fetched the things associated with the user
}
override fun error(error: FetchThingsError?) {
when (error) {
FetchThingsError.RequiresRelogin -> {}
FetchThingsError.ConnectivityError -> {}
FetchThingsError.GeneralError -> {}
}
}
})
Fetch user’s single associated thing
It is also possible to fetch a specific Thing by providing its physical ID instead of fetching all of the associated Things for a given User.
💡 In order to fetch a given Thing consider saving the
physicalIdof the thing locally.
Result model - Thing
Please refer the Thing entity.
Result error - FetchSingleThingError
ThingNotFound- The requested thing physical ID cannot be found.ThingIsNotAssociated- The requested thing physical ID is not associated to current user.InvalidParameters- One or more of provided parameters is missing or invalid.RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.fetchThing(withPhysicalId: "ConnectedSupermanCape17")
.build()
.execute { (response) in
switch response {
case .success(let thing):
break
case .failure(error: let fetchError):
switch(fetchError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
case .thingNotFound(let debugMessage):
break
case .thingIsNotAssociated(let debugMessage):
break
case .invalidParameters(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.Thing
.fetchThing("physicalId")
.build()
.execute(new RequestListener<ThingModel, FetchSingleThingError>() {
@Override
public void success(ThingModel response) {
// Fetched thing by physicalId with success
}
@Override
public void error(FetchSingleThingError error) {
switch (error) {
case ThingNotFound:
break;
case ThingIsNotAssociated:
break;
case InvalidParameters:
break;
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.Thing
.fetchThing("physicalId")
.build()
.execute(object : RequestListener<ThingModel?, FetchSingleThingError?> {
override fun success(response: ThingModel?) {
// Fetched thing by physicalId with success
}
override fun error(error: FetchSingleThingError?) {
when (error) {
FetchSingleThingError.ThingNotFound -> {}
FetchSingleThingError.ThingIsNotAssociated -> {}
FetchSingleThingError.InvalidParameters -> {}
FetchSingleThingError.RequiresRelogin -> {}
FetchSingleThingError.ConnectivityError -> {}
FetchSingleThingError.GeneralError -> {}
}
}
})
Update thing details
Things associated with Copilot.cx Users may be updated. The following parameters can be updated for a given Thing by providing the Thing’s physicalId:
Name- Specific alias (String) provided by the end-user for a specific hardware Thing.You may want to first associate a specific Thing to a User, and then allow the user to name it (provide an alias).
Status- Update a given Thing’s current status. Please refer theThingentity for more details.Firmware- Firmware version recorded in the latest communication with the hardware Thing.CustomSettings
Result model - Thing
Please refer the Thing entity.
Result error - UpdateThingError
ThingNotFound- The requested thing physical ID cannot be found.ThingIsNotAssociated- The requested thing physical ID is not associated to current user.InvalidParameters- One or more of provided parameters is missing or invalid.RequiresRelogin- Session expired and cannot be regained, please relogin.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Copilot.instance
.manage
.sphere
.thing
.updateThing(withPhysicalId: "ConnectedSupermanCape17")
.with(name: "Coolest cape ever")
.with(firmware: "2.3")
.with(status: ThingStatus(lastSeen: Date(), reportedStatuses: []))
.with(customValue: true, forKey: "autoDetection").build().execute { (response) in
switch response {
case .success(let thing):
break
case .failure(error: let updateThingError):
switch(updateThingError) {
case .generalError(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .requiresRelogin(let debugMessage):
break
case .thingNotFound(let debugMessage):
break
case .thingIsNotAssociated(let debugMessage):
break
case .invalidParameters(let debugMessage):
break
}
}
}
List<ThingReportedStatusModel> reportedStatues = new ArrayList<>();
reportedStatues.add(new ThingReportedStatusModel(new java.util.Date(System.currentTimeMillis()), "online", "yes"));
reportedStatues.add(new ThingReportedStatusModel(new java.util.Date(System.currentTimeMillis()), "working", "no"));
Copilot.getInstance()
.Manage
.Sphere
.Thing
.updateThing("physicalId")
.withName("Daily Planet Meeting Room 1")
.withFirmware("2.3")
.withStatus(new ThingStatusModel(new java.util.Date(System.currentTimeMillis()), reportedStatues))
.withCustomValue("autoDetection", true)
.build()
.execute(new RequestListener<ThingModel, UpdateThingError>() {
@Override
public void success(ThingModel response) {
// Updated thing with success
}
@Override
public void error(UpdateThingError error) {
switch (error) {
case ThingNotFound:
break;
case ThingIsNotAssociated:
break;
case InvalidParameters:
break;
case RequiresRelogin:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
val reportedStatues = arrayListOf(
ThingReportedStatusModel(Date(System.currentTimeMillis()), "online", "yes"),
ThingReportedStatusModel(Date(System.currentTimeMillis()), "working", "no")
)
Copilot.getInstance()
.Manage
.Sphere
.Thing
.updateThing("physicalId")
.withName("Daily Planet Meeting Room 1")
.withFirmware("2.3")
.withStatus(ThingStatusModel(Date(System.currentTimeMillis()), reportedStatues))
.withCustomValue("autoDetection", true)
.build()
.execute(object : RequestListener<ThingModel?, UpdateThingError?> {
override fun success(response: ThingModel?) {
// Updated thing with success
}
override fun error(error: UpdateThingError?) {
when (error) {
UpdateThingError.ThingNotFound -> {}
UpdateThingError.ThingIsNotAssociated -> {}
UpdateThingError.InvalidParameters -> {}
UpdateThingError.RequiresRelogin -> {}
UpdateThingError.ConnectivityError -> {}
UpdateThingError.GeneralError -> {}
}
}
})