Home Information Management

Last Updated on : 2026-02-13 06:55:50download

After login into the app, call TSmartHomeManager to get a list of homes. Then, initialize an object of the TSmartHome class to get the details of a specific home. This enables device control for the home.

Functional description

Class name	Description
TSmartHomeManager	Query the list of homes, add homes, manage the current home, and invite members.
TSmartHome	Manage information for a single home, get all devices and groups in the home, and query home details.
ITSmartHomeChangeListener	Callback listener for home list changes.
ITSmartHomeStatusListener	Callback listener for changes to specific home information.

TSmartHome must be initialized with the correct value of homeId to implement information management for a single home. An incorrect homeId might cause failed initialization. Information management for a single home includes the capabilities to manage devices, groups, rooms, and other resources of the home.

To get all devices and groups in a home, you must first initialize the TSmartHome object and query the home details using getHomeDetail(callback). Then, the TSmartHome instance will contain complete data.

Create a home

API description

public async addHome(params: TSmartCreateHomeDataParams): Promise<TSmartAtopResponse<TSmartHomeBean>>

Parameters

TSmartCreateHomeDataParams structure

Parameter	Description
name	The name of a home.
geoName	The geographical location of a home (city name).
latitude	The latitude of the home.
longitude	The longitude of the home.
rooms	A list of room names for the home.

Return values

Returns Promise<TSmartAtopResponse<TSmartHomeBean>>, containing the created home information.

Sample code

import { TSmartHomeManager } from '@thingsmart/homelib';
import { TSmartCreateHomeDataParams } from '@thingsmart/homelib';

const homeManager = TSmartHomeManager.getInstance();

const params: TSmartCreateHomeDataParams = {
  name: 'My Home',
  geoName: 'Beijing',
  latitude: 39.9042,
  longitude: 116.4074,
  rooms: ['Living Room', 'Bedroom', 'Kitchen']
};

try {
  const response = await homeManager.addHome(params);
  if (response.success) {
    const homeBean = response.result;
    console.log('Home was created successfully, Home ID:', homeBean.homeId);
  } else {
    console.error('Failed to create a home:', response.errorMsg);
  }
} catch (error) {
  console.error('An error occurred when creating a home:', error);
}

Query a list of homes

Returns a simple list of homes. To query details for a specific home, you need to initialize a home in the TSmartHome instance and call the getHomeDetail(callback) interface.

API description

public async getHomeList(): Promise<TSmartAtopResponse<Array<TSmartHomeBean>>>

Return values

Returns Promise<TSmartAtopResponse<Array<TSmartHomeBean>>>, containing the list of homes.

Sample code

const homeManager = TSmartHomeManager.getInstance();

try {
  const response = await homeManager.getHomeList();
  if (response.success) {
    const homeList = response.result;
    homeList.forEach((home) => {
      console.log('Home ID:', home.homeId, 'Home name:', home.homeName);
    });
  } else {
    console.error('Failed to get a home list:', response.errorMsg);
  }
} catch (error) {
  console.error('An error occurred when getting a home list:', error);
}

Update home information

API description

public async updateHome(updateHomeInfoParams: TSmartUpdateHomeDataParams): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Description
updateHomeInfoParams	The parameter object for updating home information.

TSmartUpdateHomeDataParams structure

Parameter	Description
name	The name of the home.
geoName	The geographical location of a home.
latitude	The latitude of the home.
longitude	The longitude of the home.

Sample code

import { TSmartHome } from '@thingsmart/homelib';
import { TSmartUpdateHomeDataParams } from '@thingsmart/homelib';

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const params: TSmartUpdateHomeDataParams = {
  name: 'New Home Name',
  geoName: 'Shanghai',
  latitude: 31.2304,
  longitude: 121.4737
};

try {
  const response = await smartHome.updateHome(params);
  if (response.success) {
    console.log('Updated home information successfully');
  } else {
    console.error('Failed to update home information:', response.errorMsg);
  }
} catch (error) {
  console.error('An error occurred when updating home information:', error);
}

Remove or cancel a home

API description

After a home is removed, all devices in the home will be reset.

public async deleteHome(): Promise<TSmartAtopResponse<boolean>>

Sample code

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const response = await smartHome.deleteHome();
  if (response.success) {
    console.log('Deleted the home successfully');
  } else {
    console.error('Failed to delete the home:', response.errorMsg);
  }
} catch (error) {
  console.error('An error occurred when deleting the home:', error);
}

Query home details

Only after calling this interface will the TSmartHome instance object contain complete data, including lists of rooms, devices, and groups.

API description

public getHomeDetail(callback: (homeBean?: TSmartHomeBean) => void): void

Parameters

Parameter	Description
callback	The callback function. The parameter is the home details object.

Sample code

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

smartHome.getHomeDetail((homeBean?: TSmartHomeBean) => {
  if (homeBean) {
    console.log('Home ID:', homeBean.homeId);
    console.log('Home Name:', homeBean.homeName);
    console.log('Room List:', homeBean.rooms);

    // Get the device list
    homeBean.getDeviceList().then((deviceList) => {
      console.log('Number of devices:', deviceList.length);
    });
  } else {
    console.error('Failed to query home details');
  }
});

Query home details asynchronously

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const homeBean = await smartHome.getHomeDetailAsync();
  if (homeBean) {
    console.log('Home details:', homeBean);
  }
} catch (error) {
  console.error('An error occurred when querying home details:', error);
}

Sort devices and groups in a home

API description

public async sortDeviceAndGroup(params: DeviceAndGroupInHomeParams): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Description
params	The sorting parameter object.

DeviceAndGroupInHomeParams structure

Parameter	Description
list	The list of sorted devices and groups.

List array elements

Field	Description
bizId	The device ID. `devId` indicates the ID of an individual device. `groupId` indicates the ID of a device group.
bizType	The business type. `TSmartHomeResBizType.DEVICE`: Device. `TSmartHomeResBizType.GROUP`: Group.

Sample code

import { TSmartHome, DeviceAndGroupInHomeParams, TSmartHomeResBizType } from '@thingsmart/homelib';

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const params: DeviceAndGroupInHomeParams = {
  list: [
    { bizId: 'device_id_1', bizType: TSmartHomeResBizType.DEVICE },
    { bizId: 'group_id_1', bizType: TSmartHomeResBizType.GROUP },
    { bizId: 'device_id_2', bizType: TSmartHomeResBizType.DEVICE }
  ]
};

try {
  const response = await smartHome.sortDeviceAndGroup(params);
  if (response.success) {
    console.log('Sorted devices and groups successfully');
  }
} catch (error) {
  console.error('An error occurred when sorting:', error);
}

Callbacks of home list changes

After implementing the ITSmartHomeChangeListener, you can handle changes in the home list in the callback.

Register a listener for changes in the home list

API description

public registerHomeChangeListener(homeChangeListener: ITSmartHomeChangeListener): void

ITSmartHomeChangeListener definition

interface ITSmartHomeChangeListener {
  /**
   * The callback invoked when a new home is added.
   */
  onHomeAdded?(homeBean: TSmartHomeBean): void;  
  /**
   * The callback invoked when a home is removed.
   */
  onHomeRemoved?(homeId: number): void;  
  /**
   * The callback invoked when home information is updated.
   */
  onHomeInfoChanged?(homeBean: TSmartHomeBean): void;  
  /**
   * The callback invoked when the current home is switched.
   */
  onCurrentHomeChanged?(homeId: number, homeName: string): void;  
  /**
   * The callback invoked when the MQTT service connection is successful.
   */
  onServerConnected?(): void; }

Sample code

import { TSmartHomeManager, ITSmartHomeChangeListener, TSmartHomeBean } from '@thingsmart/homelib';

class MyHomeListener implements ITSmartHomeChangeListener {
  onHomeAdded(homeBean: TSmartHomeBean): void {
    console.log('Add a home:', homeBean.homeName);
  }

  onHomeRemoved(homeId: number): void {
    console.log('Remove a home:', homeId);
  }

  onHomeInfoChanged(homeBean: TSmartHomeBean): void {
    console.log('Update home information:', homeBean.homeName);
  }

  onCurrentHomeChanged(homeId: number, homeName: string): void {
    console.log('Switch to another home:', homeName);
  }

  onServerConnected(): void {
    console.log('MQTT connection successful, it is recommended to query home details again');
    // Re-query the current home details to ensure the data is up-to-date.
  }
}

// Register a listener.
const homeManager = TSmartHomeManager.getInstance();
const listener = new MyHomeListener();
homeManager.registerHomeChangeListener(listener);

Unregister a listener for changes in the home list

API description

public unRegisterHomeChangeListener(homeChangeListener: ITSmartHomeChangeListener): void

Sample code

const homeManager = TSmartHomeManager.getInstance();
homeManager.unRegisterHomeChangeListener(listener);

Cancel all listeners for changes in the home list

API description

public unRegisterAllHomeChangeListener(): void

Sample code

const homeManager = TSmartHomeManager.getInstance();
homeManager.unRegisterAllHomeChangeListener();

Callbacks of home information changes

After implementing the ITSmartHomeStatusListener, you can handle changes in the callback of a single home information change.

Register a listener for changes in the home information

API description

public registerHomeStatusListener(listener: ITSmartHomeStatusListener): void

ITSmartHomeStatusListener definition

interface ITSmartHomeStatusListener {
  /**
   * The callback invoked when home information is updated.
   */
  onHomeInfoChanged?(homeBean: TSmartHomeBean): void;  
  /**
   * The callback invoked when the list of shared devices changes.
   */
  onSharedDeviceList?(homeId: number): void;  
  /**
   * The callback invoked when the list of shared groups changes.
   */
  onSharedGroupList?(homeId: number): void;  
  /**
   * The callback invoked when a room is added.
   */
  onRoomAdded?(roomBean: TSmartRoomBean): void;  
  /**
   * The callback invoked when a room is removed.
   */
  onRoomRemoved?(roomId: number): void;  
  /**
   * The callback invoked when room information is updated.
   */
  onRoomInfoChanged?(roomBean: TSmartRoomBean): void;  
  /**
   * The callback invoked when a device is added.
   */
  onDeviceAdded?(deviceBean: TSmartDeviceModel): void;  
  /**
   * The callback invoked when a device is removed.
   */
  onDeviceRemoved?(devId: string): void;  
  /**
   * The callback invoked when device information is updated.
   */
  onDeviceInfoChanged?(deviceBean: TSmartDeviceModel): void;  
  /**
   * The callback invoked when device DP data is updated.
   */
  onDeviceDpUpdate?(deviceBean: TSmartDeviceModel, dps: Record<string, Object>): void;  
  /**
   * The callback invoked when a group is added.
   */
  onGroupAdded?(groupBean: TSmartGroupModel): void;  
  /**
   * The callback invoked when a group is removed.
   */
  onGroupRemoved?(groupId: string): void;  
  /**
   * The callback invoked when group information is updated.
   */
  onGroupInfoChanged?(groupBean: TSmartGroupModel): void;  
  /**
   * The callback invoked when group DP data is updated.
   */
  onGroupDpUpdate?(groupBean: TSmartGroupModel, dps: Record<string, Object>): void;
}

Sample code

import { TSmartHome, ITSmartHomeStatusListener, TSmartHomeBean } from '@thingsmart/homelib';

class MyHomeStatusListener implements ITSmartHomeStatusListener {
  onHomeInfoChanged(homeBean: TSmartHomeBean): void {
    console.log('Update home information:', homeBean.homeName);
  }

  onRoomAdded(roomBean: TSmartRoomBean): void {
    console.log('Add a room:', roomBean.name);
  }

  onDeviceAdded(deviceBean: TSmartDeviceModel): void {
    console.log('Add a device:', deviceBean.name);
  }

  onDeviceDpUpdate(deviceBean: TSmartDeviceModel, dps: Record<string, Object>): void {
    console.log('Update device data:', deviceBean.devId, dps);
  }
}

// Register a listener
const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);
const listener = new MyHomeStatusListener();
smartHome.registerHomeStatusListener(listener);

Unregister a listener for changes in the home information

API description

public unRegisterHomeStatusListener(listener: ITSmartHomeStatusListener): void

Sample code

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);
smartHome.unRegisterHomeStatusListener(listener);

Query weather of the home location

Query weather overview

API description

Returns the weather overview of the city where the home is located. Weather data includes the city name, weather conditions, such as sunny, cloudy, or rainy, and weather icons.

public async getHomeWeatherSketch(): Promise<TSmartAtopResponse<TSmartWeatherSketchBean>>

Return values

TSmartWeatherSketchBean structure

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

Sample code

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const response = await smartHome.getHomeWeatherSketch();
  if (response.success) {
    const weather = response.result;
    console.log('Weather:', weather.condition);
    console.log('Temperature:', weather.temp);
    console.log('Icon:', weather.iconUrl);
  }
} catch (error) {
  console.error('Failed to query the weather:', error);
}

Query weather details

API description

Returns the weather details for the city where the home is located. Multiple types of weather data are returned, such as the temperature, humidity, ultraviolet (UV) index, and air quality.

public async getHomeWeatherDetail(optionParams?: TSmartWeatherOptionParams): Promise<TSmartAtopResponse<Array<TSmartWeatherBean>>>

Parameters

Parameter	Description
optionParams	(Optional) The unit settings of the weather details.

TSmartWeatherOptionParams structure

Parameter	Description
pressureUnit	The unit of air pressure.
windspeedUnit	The unit of wind speed.
temperatureUnit	The unit of temperature.
limit	The number of weather variables to return.

Return values

TSmartWeatherBean structure

Field	Description
icon	The URL of a weather details icon.
name	The name of a weather parameter.
unit	The unit of a parameter.
value	The value of a parameter.

Sample code

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const optionParams: TSmartWeatherOptionParams = {
  temperatureUnit: '°C',
  pressureUnit: 'hPa',
  windspeedUnit: 'm/s',
  limit: 10
};

try {
  const response = await smartHome.getHomeWeatherDetail(optionParams);
  if (response.success) {
    const weatherList = response.result;
    weatherList.forEach((weather) => {
      console.log(`${weather.name}: ${weather.value} ${weather.unit}`);
    });
  }
} catch (error) {
  console.error('Failed to query weather details:', error);
}

Prev DocHome Management

Next DocRoom Information Management