Buteo/MTP

= Introduction = The MTP applications provides the functionality of file exploration from a PC that supports the initiator role of MTP. The purpose of this wiki document is to provide the design details of the MTP stack implementation and the MTP application. The MTP application uses the stack and provides Maemo specific MTP functionality. The MTP stack provides the implementation of the standard Media Transfer Protocol (http://www.usb.org/developers/devclass_docs/MTP_1.0.zip). It uses the MTP driver which provides a combined interface for OBEX, SyncML, MTP functionality. So a Buteo Sync framework can load three plug-ins that could handle each of these interfaces at the same time. The stack is not completely backward compatible with PTP.

The MTP application does not have a UI and so does not use any MeeGoTouchUI components. The MTP application is integrated into the Synchronization framework and is provided as a client plugin (Note: currently it is a server plug-in, but this going to be changed very soon). The main reason for integrating the MTP application to the Synchronization framework is for the synchronization daemon to start the MTP application when the user connects the device to the PC. Details of the MTP integration into the Synchronization framework are provided in the following sections. Figure 1 shows the structural view of the MTP application.



The MTP application is a plug-in for the Synchronization framework and is loaded as a loadable module in a separate thread. It uses the MTP stack library for MTP protocol functionality. The Content Framework is used to retrieve information about the media files and the Context Framework is used to fetch the device specific information like battery level, device state etc. Even though DRM is listed in the diagram, only abstract interfaces for DRM are provided. No implementation is available. Once a DRM solution is chosen for MeeGo, it could be implemented. Once the files are copied to the device, tracker automatically reaps the meta-data information from the file. But not all meta-data is embedded in the file. For such cases, MTP application write the extra meta-data information to the tracker.

= Usecases = Following is the usecase diagram of MTP



The main usecases of MTP application is to synchronize media files between Nokia Music Application and the device. Theoretically, it should be possible to use the MTP application with any PC application that supports MTP1.0 specification

= MTP Stack Design = As per the MTP specification, Initiator is the entity like PC based application that sends commands to the Responder, which is a MTP service running in a hand-held device. The MeeGo device is going to be an responder (USB slave) and the PC application would be a initiator (USB master)

The MTP specification broadly constitutes the following entities:
 * Operations
 * Events
 * Objects
 * Device Information
 * Object Formats

MTP follows a operator-data-response model for all the communications. Operations are MTP operations initiated by the Initiator from the PC. Some examples of operations are, GetDeviceInfo, GetObjectHandles. Events indicate a change in a specific property of the device to be notified to the responder. An event is just a notification and does not contain the actual data. The responder is responsible for retrieving the data after receiving the event notification. Objects are any kind of objects in the responder’s device. Each object is associated with meta-data information that the initiator fetches to display the object information in the Initiator UI. For example, Nokia Music Application fetches the objects meta-data and displays the filenames and the file type information in the NMM UI. Apart from files, objects can also be other mime types, like iCal, vCal or vCard files. Synchronization of Calendar and Contacts mime-types is not in the scope of the the MTP stack. MTP specification supports some specific formats that the initiators and the responder’s can choose to support. The various formats are listed in the MTP specification [MTP_SPEC_1.0].

The directory structure of MTP stack is as below:



The Core directory will have the basic MTP operations, events and objects handling. The common directory will have the common utility functions. All the MTP core functionality, like Operations, Events and Objects are maintained in the core directory. The transport specific functionality is maintained in the transport directory, which in-turn has directories for the specific transport (like bluetooth for Bluetooth and usb for USB transports). The transport directory itself will have the transport related generic and abstract functionality. The common directory has the common utility functions. The platform directory has functionality that is specific to the implementation platform. This directory has an abstract interface to the target platform and the specific platform implementations are provided in the subdirectories. Multiple platforms will have similar set of directories. It is possible to have a platform specific directory under ‘platforms’ directory, but since currently, the current target is MeeGo, this level is not required.

= MTP Stack Features =

Almost all the major features of the MTP stack are implemented and supported. A list of non-supported features are listed below: [TBD]

= MTP Sequence Diagram = Following figure depicts the sequence flow diagram of MTP



The MTP application is invoked only on demand. The MTP application is implemented as a plug-in in the Buteo Synchronization Framework. The main reason for implementing the MTP application as a plug-in is for the synchronization daemon to load the MTP application whenever the user connects the device to the PC using the USB cable. This ensures that it is not required to run the MTP application continuously. Following is an explanation of the sequence of steps, w.r.t above figure (note that the sequence number below might not exactly match with the sequence number in the figure, but is quite close): 1.The user connects the device with the PC using the USB cable. One of the features of the Synchronization application is not to display to the user multiple options for selecting the “Ovi Suite” mode and “MTP” mode. This ensures that the user need not manually change the modes during synchronization of PIM data (using SyncML plug-in) and synchronization of media file (using MTP plug-in). In order to achieve this functionality, a separate USB MTP driver has been implemented. Since the SyncML plug-in and the MTP plug-in will be running in separate threads of the Synchronization daemon, it is possible to handle parallel synchronizations. 2.Once the USB is connected, the ke-recv (or HAL) receives a notification that sends a signal to the synchronization daemon. Since it is possible that the user can synchronize PIM data or Media data, a USB connection is taken for both the interfaces. In the current implementation, separate USB character devices are created for each kind of interface, like ‘/dev/ttyGS1’ for OBEX interface, ‘/dev/ttyGS2’ for SYNCML interface and ‘/dev/mtp0’ for MTP interface. 3.The Synchronization daemon on receiving the signal from ke-recv, launches the SyncML engine and the MTP engine in two separate threads. 4.The MTP engine opens the character device (using the standard Linux file operations). a.Note: At this stage, the MTP engine populates an internal cache of object handles of all the objects in the media repository. The information about the object handles is created by reading the information from Content Framework. Populating the objects at this stage is a matter of performance against the memory consumption. More information about the object size and the process CPU usage is discussed under the Performance section. 5.At this stage, typically the initiator issues an GetDeviceInfo operation to fetch the device specific information. A list of device specific properties along with the API used to fetch the device information. In the device info response, the MTP engine also sends information about all the operations that are supported by the device (see MTP Stack Features). 6.Based on the operation list that the initiator received in step 5 above, the initiator may choose to invoke any of the supported operations. If a GetObjects operation is invoked, then all the objects created in step 4.a above are returned to the initiator. Also the initiator may choose to synchronize media files, transfer files from/to PC/device. 7.If a media file is protected by DRM (information obtained from the DRM property of the MTP object), then the MTP engine reads the license information from the media file, uses the Maemo DRM engine API to store the license to the license store. The actual responsibility of decrypting the media file using the stored license rests with the media player. Note that if a DRM protected media file is transferred from device to PC, then the license itself is not transferred to the PC. Rather the media file has a DRM URI in its meta-data information, which the PC software uses to retrieve the license from the network. 8.Once the device is disconnected from the PC, the ke-recv daemon sends a signal again to the Synchronization daemon, which will inturn send a signal to MTP engine. The MTP engine will then do the necessary cleanup operations (releasing the USB connection being one of them) and finally sends a signal to daemon. 9.The daemon will then unload the MTP engine. Note that there are no UI operations involved in this process

= Configurability = The device information is configurable by adding new codec types and new support for media content. Refer to the deviceinfo.xml file in the code (http://meego.gitorious.org/meego-middleware/buteo-mtp/blobs/master/mts/deviceinfo.xml)

= Packages = The main components of the MTP application include the MTP stack library (libmeegomtp) and the MTP plug-in itself.
 * libmaemomtp
 * libmaemomtp-dev
 * libmaemomtp-doc
 * libmaemomtp-dbg