You are here: MyURC.org > Tools & Prototypes > UCHj > tutorial > How to write a TDM

How to Write a Target Discovery Module (TDM)

---

Page Content:

---

Understand the UCH Architecture

You should be familiar with the URC framework and the UCH architecture.

Here are some useful documents:

• URC Technical Primer
• Universal Control Hub specification

Write Your TDM

Your TDM must implement the ITDM interface, and may use any method of the ITDMListener interface.

ITDM has the following methods:

• void init(ITDMListener tdmListener, Map tdmProps, Map uchProps, Map[] contexts) throws TDMFatalException
  • init() is called only once by the UCH prior to any other method of TDM. UCH instantiates TDMs for starting discovery of particular device(s) for certain networking platforms.
  • Map[] contexts specifies a list of contexts, and every context contains one userProfile and one controllerProfile that provides properties of User and Controller respectively. 'null' value of contexts specifies availablility for all users and controllers. Store the contexts for further usage. If TDM doesn't want to restrict any Target based on userProfile and controllerProfile then no need to do any implementation regarding to contexts.

• void contextsOpened(Map[] Contexts) throws TDMFatalException
  • It is called when new contexts are added in UCH.
  • TDM should add these contexts to stored context's.
  • TDM should call the method ITDMListener.targetContextsAdded(string targetId, Map[] Contexts). If TDM doesn't want to restrict targets based on userProfile and controllerProfile then no need to do any implementation regarding contexts.

• void contextsClosed(Map[] Contexts) throws TDMFatalException
  • It is called when new contexts are removed for specified target.
  • TDM should remove these contexts from stored context's.
  • TDM should call the method ITDMListener.targetContextsRemoved(string targetId, Map[] Contexts). If TDM doesn't want to restrict targets based on userProfile and controllerProfile then no need to do any implementation regarding to contexts.

• void startDiscovery()
  • Will start the discovery engine for discovering different devices in the network supporting the protocol for which the TDM has been written.
  • On discovering the device, a taProps map has to be created with following keys (please read Resource Property Vocabulary 1.0, Draft Technical Report 2009-11-03):
    • http://myurc.org/ns/res#type : value will be 'http://myurc.org/restypes#ta'
    • http://purl.org/dc/terms/conformsTo : value as per conforming UCH specification
    • http://myurc.org/ns/res#devicePlatform
    • http://myurc.org/ns/res#deviceType
  • On discovering the device, a targetProps map has to be created with following keys (please read Resource Property Vocabulary 1.0, Draft Technical Report 2009-11-03):
    • http://myurc.org/ns/res#type : value will be 'http://myurc.org/TR/uch/#target' in this case.
    • http://myurc.org/ns/res#instanceId
    • http://myurc.org/ns/res#targetFriendlyName
    • http://myurc.org/ns/res#devicePlatform
    • http://myurc.org/ns/res#deviceType
    • http://myurc.org/ns/res#modelName
  • These maps (ta property map and target property map) have to be passed to the method - ITDMListener.targetDiscovered(Map targetProps, Map taProps, Map[] contexts).
  • The UCH shall return the targetId (string) that it has assigned the newly discovered target. This may be identical to the property ‘http://myurc.org/ns/res#instanceId’ in targetProps, if globally unique. NULL if the UCH does not instantiate a Target Adapter for this target, and does not want to be notified when the target will be discarded.
  • Using the above properties, UCH will search for the appropriate TA for the discovered target and accordingly initialize the TA and register the discovered target. Also the above target property map will be passed to the TA from the UCH.
  • TDM also needs to implement proper mechanism for detecting that a target has been discarded from the network. On discard detection, the TDM has to call the method ITDMListener.targetDiscarded(string targetId)

• void stopDiscovery()
  • Stop discovering devices in the network.

• Map getTDMProps()
  • Get Property Map of the TDM, which was passed to the TDM when initialized.

• void finalize()
  • Clear the memory held by the TDM.

Configure UCHj to use your TDM

Please refer to How to Add Local Resources.

---

Last update: Parikshit Thakur & Team, Gottfried Zimmermann, 2010-04-08