Home Information Management

This topic describes how to implement the features of home management using APIs. These APIs allow you to create, modify, delete, and join a home, get home and weather information, and register listeners for receiving room-based event callbacks.

Feature description

The class ThingSmartFamilyBiz is used for home management to implement operations on a home.

Class (or protocol)	Description
ThingSmartFamilyBiz	The home management class.
ThingSmartHomeModel	The coarse-grained home model.
ThingSmartHome	The fine-grained home model.
ThingSmartFamilyBizDelegate	The home delegate protocol.

Data model of ThingSmartHomeModel

Field	Type	Description
homeId	long long	The home ID.
name	NSString	The name of a home.
geoName	NSString	The location of the home.
latitude	double	The latitude of the home.
longitude	double	The longitude of the home.

API list

Create a default home

If no home exists under the user account, create a default home and pass in the home name. Make a callback on success to return homeId.
Additionally, you can register a listener and implement the delegate method ThingSmartFamilyBizDelegate to receive a callback when a default home is created.

API description

- (void)createDefaultFamilyWithName:(NSString *)name
                            success:(void(^)(long long homeId))success
                            failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
name	The name of a home.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)createDefaultFamily {
    [[ThingSmartFamilyBiz sharedInstance] createDefaultFamilyWithName:@"" success:^(long long homeId) {

    } failure:^(NSError *error) {

    }];
}

Swift:

 func createDefaultFamily() {
    ThingSmartFamilyBiz.sharedInstance().createDefaultFamily(withName: "") { homeId in

    } failure: { error in

    }
}

Create a home

The user creates a home with the necessary information, including home name, room, and location. Make a callback on success to return homeId.
Additionally, you can register a listener and implement the delegate method ThingSmartFamilyBizDelegate to receive a callback when a home is created.

API description

- (void)addFamilyWithModel:(ThingSmartFamilyRequestModel *)model
                   success:(void(^)(long long homeId))success
                   failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
model	The request model to create a home.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartFamilyRequestModel

Field	Type	Description
name	NSString	The name of a home.
geoName	NSString	The name of the city where the home is located.
latitude	double	The latitude of the home.
longitude	double	The longitude of the home.
rooms	NSArray	The list of room names in a home.

Example

Objective-C:

- (void)addFamily {
    ThingSmartFamilyRequestModel *requestModel = [[ThingSmartFamilyRequestModel alloc] init];
    requestModel.geoName = @"";
    requestModel.latitude = 3;
    requestModel.longitude = 45;
    requestModel.name = @"family name";
    requestModel.rooms = @[];
    [[ThingSmartFamilyBiz sharedInstance] addFamilyWithModel:requestModel success:^(long long homeId) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func addFamily() {
    let requestModel = ThingSmartFamilyRequestModel()
    requestModel.geoName = ""
    requestModel.latitude = 3
    requestModel.longitude = 45
    requestModel.name = "family name"
    requestModel.rooms = []
    ThingSmartFamilyBiz.sharedInstance().addFamily(with: requestModel) { homeId in

    } failure: { error in

    }
}

Delete a home

The home owner deletes a home. All the devices in the home will be reset.
Additionally, you can register a listener and implement the delegate method ThingSmartFamilyBizDelegate to receive a callback when a home is deleted.

API description

- (void)deleteFamilyWithHomeId:(long long)homeId
                       success:(ThingSuccessHandler)success
                       failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)removeFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] deleteFamilyWithHomeId:homeId success:^{

    } failure:^(NSError *error) {

    }];
}

Swift:

func removeFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().deleteFamily(withHomeId: homeId) {

    } fai
lure: { error in

    }
}

Update home information

Update the location, name, latitude and longitude, and rooms of a home.
Additionally, you can register a listener and implement the delegate method ThingSmartFamilyBizDelegate to receive a callback when a home is updated.

API description

- (void)updateFamilyWithHomeId:(long long)homeId
                         model:(ThingSmartFamilyRequestModel *)model
                       success:(ThingSuccessHandler)success
                       failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
model	The request model to update a home.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartFamilyRequestModel

Field	Type	Description
name	NSString	The name of a home.
geoName	NSString	The name of the city where the home is located.
latitude	double	The latitude of the home.
longitude	double	The longitude of the home.
rooms	NSArray	The list of room names in a home.

Example

Objective-C:

- (void)updateFamily:(long long)homeId {
    ThingSmartFamilyRequestModel *requestModel = [[ThingSmartFamilyRequestModel alloc] init];
    requestModel.geoName = @"";
    requestModel.latitude = 123;
    requestModel.longitude = 30;
    requestModel.name = @"new family name";
    requestModel.rooms = @[];
    [[ThingSmartFamilyBiz sharedInstance] updateFamilyWithHomeId:homeId model:requestModel success:^{

    } failure:^(NSError *error) {

    }];
}

Swift:

func updateFamily(homeId:Int64) {
    let requestModel = ThingSmartFamilyRequestModel()
    requestModel.geoName = ""
    requestModel.latitude = 123
    requestModel.longitude = 30
    requestModel.name = "new family name"
    requestModel.rooms = []
    ThingSmartFamilyBiz.sharedInstance().updateFamily(withHomeId: homeId, model: requestModel) {

    } failure: { error in

    }
}

Get coarse-grained home information

Get the list of all homes under an account.

API description

- (void)getFamilyListWithSuccess:(void(^)(NSArray<ThingSmartHomeModel *> * homes))success
                         failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)getFamilyList {
    [[ThingSmartFamilyBiz sharedInstance] getFamilyListWithSuccess:^(NSArray<ThingSmartHomeModel *> *homes) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getFamilyList() {
    ThingSmartFamilyBiz.sharedInstance().getFamilyList { familyList in

    } failure: { error in

    }
}

Get the list of cache homes

After the request for the list of cache homes is completed, the list will be updated automatically. After [ThingSmartFamilyBiz getFamilyListWithSuccess:failure:] is called, the data can be fed to the list of cache homes.

API description

- (NSArray <ThingSmartHomeModel *>*)getCachedHomes;

Return value

The cache home model. For more information, see the data model ThingSmartHomeModel.

Example

Objective-C:

[[ThingSmartFamilyBiz sharedInstance] getCachedHomes];

Swift:

ThingSmartFamilyBiz.sharedInstance().getCachedHomes()

Get home details

Get the details of a home, including the list of rooms, devices, and groups.

API description

- (void)getFamilyDetailWithHomeId:(long long)homeId
                          success:(void(^)(ThingSmartHome *home))success
                          failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)getFamilyDetail:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] getFamilyDetailWithHomeId:homeId success:^(ThingSmartHome *home) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getFamilyDetail(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().getFamilyDetail(withHomeId: homeId) { home in

    } failure: { error in

    }
}

Get the information about the city of home

API description

- (void)getCityInfo:(double)latitude
          longitude:(double)longitude
            success:(void(^)(ThingSmartFamilyCityModel *cityModel))success
            failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
latitude	The latitude of the home.
longitude	The longitude of the home.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartFamilyCityModel

Field	Type	Description
area	NSString	The area where the home is located.
province	NSString	The province where the home is located.
city	NSString	The city where the home is located.

Example

Objective-C:

- (void)getFamilyCity {
    [[ThingSmartFamilyBiz sharedInstance] getCityInfo:12 longitude:12 success:^(ThingSmartFamilyCityModel *cityModel) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getFamilyCity() {
    ThingSmartFamilyBiz.sharedInstance().getCityInfo(12, longitude: 12) { cityInfo in

    } failure: { error in

    }
}

Get coarse-grained weather data

Get the weather overview of the city where the home is located, including the city name, weather conditions (such as sunny, cloudy, or rainy), and weather icons.

API description

- (void)getHomeWeatherSketchWithHomeId:(long long)homeId
                               success:(void(^)(ThingSmartWeatherSketchModel *))success
                               failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartWeatherSketchModel

Field	Type	Description
condition	NSString	The weather conditions, such as sunny, cloudy, and rainy.
iconUrl	NSString	The URL of a weather icon.
inIconUrl	NSString	The URL of a highlighted weather icon.
temp	NSString	The temperature.

Example

Objective-C:

- (void)getWeather:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] getHomeWeatherSketchWithHomeId:homeId success:^(ThingSmartWeatherSketchModel *weather) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getWeather(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().getHomeWeatherSketch(withHomeId: homeId) { weather in

    } failure: { error in

    }
}

Get fine-grained weather data

API description

- (void)getHomeWeatherDetailWithHomeId:(long long)homeId
                                option:(ThingSmartWeatherOptionModel *)optionModel
                               success:(void(^)(NSArray<ThingSmartWeatherModel *> *))success
                               failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
optionModel	The model for setting the unit to measure a weather variable.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartWeatherOptionModel

Field	Type	Description
pressureUnit	ThingSmartWeatherOptionPressureUnit	The unit of atmospheric pressure.
windspeedUnit	ThingSmartWeatherOptionWindSpeedUnit	The unit of wind speed.
temperatureUnit	ThingSmartWeatherOptionTemperatureUnit	The unit of temperature.
limit	NSInteger	The number of weather variables to return. If not set, all weather variables are returned.

Data model of ThingSmartWeatherModel

Field	Type	Description
icon	NSString	The URL of the icon for a weather variable.
name	NSString	The name of a weather variable.
unit	NSString	The unit of a weather variable.
value	NSString	The value of a weather variable.

Example

Objective-C:

- (void)getWeatherDetail:(long long)homeId {
    ThingSmartWeatherOptionModel *option = [[ThingSmartWeatherOptionModel alloc] init];
    option.pressureUnit = ThingSmartWeatherOptionPressureUnit_hPa;
    [[ThingSmartFamilyBiz sharedInstance] getHomeWeatherDetailWithHomeId:homeId option:option success:^(NSArray<ThingSmartWeatherModel *> *weathers) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getWeatherDetail(homeId:Int64) {
    let option = ThingSmartWeatherOptionModel()
    ThingSmartFamilyBiz.sharedInstance().getHomeWeatherDetail(withHomeId: homeId, option: option) { weathers in

    } failure: { error in

    }
}

Leave a home

Remove a member from a home. A home owner can remove an admin and a role with low privileges. An admin can remove a common member and a role with low privileges.

Member information management defines three types of roles (ThingHomeRoleType):

• owner: Home owner
• admin: Admin
• member: Common member

The result of leaving a home varies by the role of a memberId.

• After a home admin or common member leaves a home, the home will not be dismissed and all the devices in the home will not be reset.
• After a home owner leaves a home, the home will be dismissed and all the devices in the home will be reset, the same as the result of deleting a home.

API description

- (void)leaveFamilyWithHomeId:(long long)homeId
                     memberId:(long long)memberId
                      success:(ThingSuccessHandler)success
                      failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
memberId	The ID of the member to leave.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)leaveFamily:(long long)homeId memberId:(long long)memberId {
    [[ThingSmartFamilyBiz sharedInstance] leaveFamilyWithHomeId:homeId memberId:memberId success:^{

    } failure:^(NSError *error) {

    }];
}

Swift:

func leaveFamily(homeId:Int64, memberId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().leaveFamily(withHomeId: homeId, memberId: memberId) {

    } failure: { error in

    }
}

Join a home with an invitation code

The user can join a home with an invitation code.

API description

- (void)joinFamilyWithInvitationCode:(NSString *)invitationCode
                             success:(ThingSuccessBOOL)success
                             failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
invitationCode	The invitation code.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)joinFamily:(NSString *)invitationCode {
    [[ThingSmartFamilyBiz sharedInstance] joinFamilyWithInvitationCode:invitationCode success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func joinFamily(invitationCode:String) {
    ThingSmartFamilyBiz.sharedInstance().joinFamily(withInvitationCode: invitationCode) { result in

    } failure: { error in

    }
}

Accept an invitation to join a home

If autoAccept is set to NO in the Add Home Member API, the invitee’s account can join a home only after accepting the invitation.

API description

- (void)acceptJoinFamilyWithHomeId:(long long)homeId
                           success:(ThingSuccessBOOL)success
                           failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The ID of the home to join.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)acceptFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] acceptJoinFamilyWithHomeId:homeId success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func acceptFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().acceptJoinFamily(withHomeId: homeId) { result in

    } failure: { error in

    }
}

Decline an invitation to join a home

If autoAccept is set to NO in the Add Home Member API, the invitee’s account can join a home only after accepting the invitation. This method is called when the invitee declines an invitation.

API description

- (void)rejectJoinFamilyWithHomeId:(long long)homeId
                           success:(ThingSuccessBOOL)success
                           failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The ID of the home to join.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)rejectFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] rejectJoinFamilyWithHomeId:homeId success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func rejectFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().rejectJoinFamily(withHomeId: homeId) { result in

    } failure: { error in

    }
}

Sort devices and groups in a home

API description

- (void)sortDeviceOrGroupWithHomeId:(long long)homeId
                          orderList:(NSArray<ThingSmartFamilyDeviceGroupOrderRequestModel *> *)orderList
                            success:(ThingSuccessHandler)success
                            failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The home ID.
orderList	The ordered list.
success	The success callback.
failure	The failure callback.

Data model of ThingSmartFamilyDeviceGroupOrderRequestModel

Field	Type	Description
bizId	NSString	The device ID or group ID.
bizType	ThingSmartFamilyParentBizType	The type of bIzId: ThingSmartFamilyParentBizTypeGroup: Group ThingSmartFamilyParentBizTypeDevice: Device

Example

Objective-C:

- (void)sortDeviceList:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] sortDeviceOrGroupWithHomeId:homeId orderList:@[] success:^{

    } failure:^(NSError *error) {

    }];
}

Swift:

func sortDeviceList(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().sortDeviceOrGroup(withHomeId: homeId, orderList: []) {

    } failure: { error in

    }
}

Get the ID of the current home

API description

- (long long)getCurrentFamilyId;

Return value

The ID of the current home.

Example

Objective-C:

[[ThingSmartFamilyBiz sharedInstance] getCurrentFamilyId];

Swift:

ThingSmartFamilyBiz.sharedInstance().getCurrentFamilyId()

Get the current home model

API description

- (ThingSmartHomeModel *)getCurrentFamily;

Return value

The home model. For more information, see the data model ThingSmartHomeModel.

Example

Objective-C:

[[ThingSmartFamilyBiz sharedInstance] getCurrentFamily];

Swift:

ThingSmartFamilyBiz.sharedInstance().getCurrentFamily()

Set the ID of the current home

When the user switches to another home, set the ID of this home and cache it.

API description

- (void)setCurrentFamilyId:(long long)homeId;

Parameter description

Parameters	Description
homeId	The home ID.

Example

Objective-C:

- (void)setCurrentFamilyId:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] setCurrentFamilyId:homeId];
}

Swift:

func setCurrentFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().setCurrentFamilyId(homeId)
}

Load the current home

After the app is launched, call this method to load the last selected current home and set appGroupName. If no current home has been selected, the first home in the list of homes is taken as the current home.

API description

- (void)launchCurrentFamilyWithAppGroupName:(NSString * _Nullable )appGroupName;

Parameter description

Parameters	Description
appGroupName	The group name shown on the app.

Example

Objective-C:

[[ThingSmartFamilyBiz sharedInstance] launchCurrentFamilyWithAppGroupName:[ThingCustomConfig sharedInstance].appGroupName];

Swift:

ThingSmartFamilyBiz.sharedInstance().launchCurrentFamilyWithAppGroupName("")

Clear the cache of the current home

API description

- (void)clearCurrentFamily;

Example

Objective-C:

[[ThingSmartFamilyBiz sharedInstance] clearCurrentFamily];

Swift:

ThingSmartFamilyBiz.sharedInstance().clearCurrentFamily()

Event callback

ThingSmartFamilyBizDelegate is the delegate protocol for the home management class. You can implement this protocol and register a listener to receive the callback for home events.

Register a listener

API description

- (void)addObserver:(id<ThingSmartFamilyBizDelegate>)observer;

Parameter description

Parameters	Description
observer	The listener.

Example

Objective-C:

- (void)addObserver:(id<ThingSmartFamilyBizDelegate>)observer {
    [[ThingSmartRoomBiz sharedInstance] addObserver:observer];
}

Swift:

func add(observer:ThingSmartFamilyBizDelegate) {
    ThingSmartRoomBiz.sharedInstance().addObserver(observer)
}

Remove a listener

API description

- (void)removeObserver:(id<ThingSmartFamilyBizDelegate>)observer;

Parameter description

Parameters	Description
observer	The listener.

Example

Objective-C:

- (void)removeObserver:(id<ThingSmartFamilyBizDelegate>)observer {
    [[ThingSmartRoomBiz sharedInstance] removeObserver:observer];
}

Swift:

func remove(observer:ThingSmartFamilyBizDelegate) {
    ThingSmartRoomBiz.sharedInstance().removeObserver(observer)
}

Home delegate

ThingSmartFamilyBizDelegate is the delegate protocol for home management. If you implement this protocol, ThingSmartFamilyBiz can notify you of home-based events (including adding or deleting a device) through a callback.

API description

@protocol ThingSmartFamilyBizDelegate <NSObject>

@optional

/**
* MQTT service connection success callback
*/
- (void)serviceConnectedSuccess;

/**
* The delegate that is instantiated when a home is added.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didAddHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing home is removed.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didRemoveHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of home update information, such as the name.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model.
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didUpdateHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of switching the current home
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didChangeCurrentHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when a new device is added.
*
* @param familyBiz            Instance of family management
* @param deviceModel       The device model
* @param homeModel            The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didAddDevice:(ThingSmartDeviceModel *)deviceModel atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing device is removed.
*
* @param familyBiz        Instance of family management
* @param deviceId          Deleted Device ID
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
  didRemoveDevice:(NSString *)deviceId
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when a new group is added.
*
* @param familyBiz         Instance of family management
* @param groupModel       The group model
* @param homeModel         The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
      didAddGroup:(ThingSmartGroupModel *)groupModel
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing group is removed.
*
* @param familyBiz        Instance of family management
* @param groupId            Deleted group ID
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
   didRemoveGroup:(NSString *)groupId
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of updates on the shared device list.
*
* @param familyBiz        Instance of family management
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
   didUpdateSharedListAtHome:(ThingSmartHomeModel *)homeModel;

@end

Parameter description

Parameters	Description
familyBiz	The home management class.
homeModel	The home model.