Hands-On Lab. Sensors & Location Platform - Native. Lab version: 1.0.0

Transcription

1 Hands-On Lab Sensors & Location Platform - Native Lab version: Last updated: 12/3/2010

2 CONTENTS OVERVIEW... 3 EXERCISE 1: ADJUSTING FONT SIZE IN RESPONSE TO AMBIENT LIGHT INTENSITY... 5 Task 1 Adding Ambient Light Awareness... 6 SUMMARY

3 Overview The Windows 7 Sensor & Location Platform enables your applications to adapt to the current environment and change the way they look, feel or behave. Here are few examples: When using a mobile PC (for example, a laptop or tablet) outdoors in a sunny day, an application might increase brightness, contrast and de-saturate colors to increase screen readability An application might provide location-specific information, such as nearby restaurants An application might use 3D accelerometer and buttons as a game controller An application might use a human presence sensor to change the state of the Messenger status Figure 1 Modified MSDN Reader that uses an ambient light sensor to change contrast, size and color saturation The Sensor & Location Platform has many advantages compared to proprietary solutions: Hardware-independence: No need to learn and invest in a particular vendor's API; all sensors types are handled very similarly Privacy: Because Microsoft recognizes that sensor and location data are private, personally identifying information, all sensors are disabled by default. You can enable/disable sensors at any time via the Control Panel. Applications might prompt you to enable specific sensors via a secure consent UI. 3

4 Application sharing: Multiple applications can consume data from the same sensor simultaneously Location simplicity: The Location API lets you obtain the location without caring about the particular mechanism used to obtain the information, for example, GPS, cell-tower or Wi-Fi hotspot triangulation. The Location API automatically chooses the most accurate sensor data available. In addition, you don't need to implement GPS protocols such as NMEA. Objectives In this Hands-On Lab, you will learn how to integrate Windows 7 Sensor support into your application, including: Detecting connected sensors Detecting sensor state Requesting user consent if access to a sensor is not enabled Handling data events from sensors System Requirements You must have the following items to complete this lab: Microsoft Visual Studio 2008 SP1 Windows 7 Windows 7 SDK Hardware with Windows 7 compatible Ambient Light Sensor with driver installed or Virtual Ambient Light Sensor 4

5 Exercise 1: Adjusting Font Size in Response to Ambient Light Intensity In this exercise, you will modify a Win32 MFC application so that it adjusts the font size used in response to varying levels of light intensity as sensed by an ambient light sensor. Most of the application's user interface is already implemented; you will have to fill in the missing parts to interact with the Windows 7 Sensor API. The end result looks like the following image To begin this exercise, open the AmbientLightAware solution (under the HOL root folder) in Visual Studio. This is a simple and standard MFC application. Spend a minute or two exploring the C++ source file (.cpp/.h) that comprises the demo application. For your convenience, ensure that the Task List tool window is visible (in the View menu, choose Task List) and in the tool window s combo box select Comments you will now see TODO items for each of the tasks in this exercise. Run the application to familiarize yourself with its looks. Note In the interests of brevity and simplicity, the demo application does not demonstrate best practices of MFC UI development, nor does it exhibit the best design guidelines for object-oriented development and COM development 5

6 Task 1 Adding Ambient Light Awareness In this task, you will add support classes and modify your application to adjust the font size of a control based on the average luminance of one or more ambient light sensors. 1. Right-click on the AmbientLightAware project and click Properties. a. Go to Linker --> Input --> Additional dependencies. b. Add sensorsapi.lib to the list. c. Click OK to close the dialog. 2. Navigate to StdAfx.h and uncomment the following includes: C++ #include <Sensors.h> #include <SensorAPI.h> 3. Right-click on the AmbientLightAware project and click Add --> Existing Item... a. Navigate to the project's directory if you're not already in it. b. Select (Ctrl-Click) the following files: AmbientLightAwareSensorManagerEvents.cpp AmbientLightAwareSensorManagerEvents.h AmbientLightAwareSensorEvents.cpp AmbientLightAwareSensorEvents.h c. Click the Add button. The Sensor API consists of the ISensorManager object, which you can use to query existing sensors by their type, category, or instance ID. You can also request permission from other users to use their sensors. In addition, you can register to be notified when new sensors become available. The CAmbientLightAwareSensorManagerEvents class serves a dual purpose: It contains the code to interact with the Sensor Manager It also implements the OnSensorEnter (new sensor becomes available) event From the Sensor Manager you can obtain ISensor objects that represent individual sensors. You can query a sensor's state and get or set other properties, such as manufacturer, model, precision, and requested update interval. You can request a data report that contains the results of measurements the sensor did. You can also register for events (sensor becomes unavailable, state changes, new data report available, generic event). The CAmbientLightAwareSensorEvents class servers a dual purpose: 6

7 It contains the code to interact with the ambient light sensor It also implements the aforementioned sensor events 4. Navigate to the top of the AmbientLightAwareSensorManagerEvents.cpp file. 5. Examine the constructor, AddRef, Release and QueryInterface methods. This is just standard COM boilerplate code. 6. Uncomment the Initialize() method. a. The code creates a Sensor Manager object (equivalent to CoCreateInstance). b. The call to SetEventSink subscribes us for the OnSensorEnter event (the class implements this event). c. By calling GetSensorsByType, we enumerate all sensors that are of type SENSOR_TYPE_AMBIENT_LIGHT. Each sensor has three GUIDs: category, type, and instance ID. Category represents what is being measured (for example, environment), Type represent how it is being measured (for example, temperature, humidity). The instance ID uniquely identifies the sensor. Instance IDs may be persistent (if a serial number is "burned" on each sensor), or non-persistent. d. The SENSOR_TYPE_AMBIENT_LIGHT #define maps to a GUID. There are many predefined sensor types in sensors.h. You can view them by right-clicking on the SENSOR_TYPE_AMBIENT_LIGHT define and selecting Go To Definition. e. We request permission to use the ambient light sensors by calling ISensorManager::RequestPermissions(), specifying the parent HWND, sensor collection and whether the function should block until the user selects what to do. This displays the following dialog: 7

8 If the user refused to enable a sensor, subsequent calls to RequestPermissions() will not show the UI. f. GetSensorsByType returns an ISensorCollection object whose item count could be determined with GetCount() and is accessed by GetAt(). g. For each sensor, we will call the AddSensor method, which we will later implement. h. Well call the GetSensorsData() method of the Sensor Events class because we want to force a fresh data report to be generated. Otherwise, the sensor may not produce a data report until the luminance has changed significantly enough. 7. Uncomment the AddSensor() method. a. The SetEventSink method of ISensor subscribes the CAmbientLightAwareSensorEvents object that we created in the constructor to this particular sensor's events (state changed, sensor detached/unavailable, and new data report). b. The sensor object is added to the m_sensors CAtlMap. 8. Uncomment the two RemoveSensor() methods. a. Uncomment the method that gets ISensor* as a parameter. The application calls this method when it wants to unsubscribe voluntarily from a particular sensor. This method is called when the application shuts down. b. Uncomment the method that gets REFSENSOR_ID as a parameter. The Sensor Events class (CAmbientLightAwareSensorEvents) calls this function when there is a forced removal of the sensor (for example, when the hardware is disconnected). This method gets a GUID and not an ISensor* because the sensor can no longer be accessed after it has been removed. 9. Uncomment the UnInitiliaze() method. This method unsubscribes from handing events of all previously subscribed to sensors. It also un-subscribes from the Sensor Manager events. This method is called when shutting down. 10. Uncomment the OnSensorEnter() method. a. This method implements ISensorManagerEvents. It is invoked when a new sensor becomes available (for example, physically attached). b. While Initialize() handles sensors which are already available at time of application startup, this method handles sensors that later become available. c. This method queries sensor state to determine if it's ready to use, and requests a data report. 11. Navigate to the top of the AmbientLightAwareSensorEvents.cpp file. 8

9 12. Examine the constructor, AddRef, Release and QueryInterface methods. This is just standard COM boilerplate code 13. Examine m_maplux. It is a CAtlMap of (SENSOR_ID to float). This map keeps track of each sensor's last recorded ambient light value (in units of Lux). The values are kept separately for each sensor so that they can be averaged later. 14. Uncomment the OnLeave() method. This method implements ISensorEvents and is invoked when a sensor becomes unavailable (that is, detached). a. This method calls the CAmbientLightAwareSensorManagerEvents::RemoveSensor() method that we previously implemented. b. The method removes the removed sensor's last ambient light value, so that it would no longer be counted when averaging. UpdateLux() is called to reflect the change by recalculating the average light intensity and by updating the UI. 15. Uncomment the OnStateChanged() method. This method implements ISensorEvents and is invoked when a sensor's state changes. When the sensor is ready, a data report is requested and the UI is updated. a. Even if a sensor is attached, it may not be ready (SENSOR_STATE_READY ) for use. The state gives the reason why. b. Another important state is SENSOR_STATE_ACCESS_DENIED, which means that permissions to use this sensor have not been granted yet in Control Panel. After you grant permissions, the state will change. You can also call ISensorManager::RequestPermissions to display the permissions dialog. c. You can query the state on demand, by calling ISensor::GetState(). 16. Uncomment the OnDataUpdated() method. This method implements ISensorEvents and is invoked when the sensor has a new data report available. Some sensors update periodically, others update when the data value(s) have changed significantly enough. In some sensors, you can control the change sensitivity by setting the SENSOR_PROPERTY_CHANGE_SENSITIVITY property with SetProperties(). 17. Uncomment the OnEvent() method. This method implements ISensorEvents and is invoked when any event fires, including OnLeave(), OnStateChanged() and OnData(). a. You can differentiate events by the event GUID. b. The reason this event exists is to allow sensors to define custom events (for example, a GPS sensor might have satellite found/lost event). In our case, we don't have custom events, so this method always returns S_OK. 18. Uncomment the UpdateLux() method. This method iterates over the m_maplux map and calculates the average value. It calls a method by the same name in the CAmbientLightAwareDlg class. 9

10 19. Uncomment the UpdateData(ISensor* psensor) method. Notice that there is another method by that name with different parameters (overload). a. This method is used throughout the code whenever we need to manually request a new data report. b. This method calls ISensor::GetData() to produce an IDataReport object. With this object, the other overload of UpdateData is called, which takes the IDataReport as a second parameter. This saves code duplication. 20. Uncomment the GetSensorData(ISensor *psensor, ISensorDataReport *pdatareport) method. This method implement ISensorEvents and is invoked when the sensor has new data available. a. The Sensor data report consists of one or more data values (fields). They can be of any number of types a PROPVARIANT supports. b. You can see the pre-determined properties by right-clicking on SENSOR_DATA_TYPE_LIGHT_LEVEL_LUX and selecting Go To Definition. The properties are grouped together in the sensors.h file, by sensor category. A comment is next to each entry specifying its data type. c. You can determine what data fields are available in a given data report by calling GetSensorValues(), which returns a key-value collection. d. You can also determine a-priori if a sensor supports a given data field by calling ISensor::SupportsDataField(). e. Use the PropVariantInit and PropVariantClear method to initialize the PROPVARIANT. f. This method updates the sensor's luminance value in the m_maplux collection and then calls UpdateLux() to recalculate and update the UI. 21. Navigate to the top of AmbientLightAwareDlg.h. Uncomment the CleanUp() and UpdateLux() method declarations. 22. Navigate to the bottom of the file. Uncomment the m_psensormanagerevents and m_lflogfont class members. 23. Navigate to the top of AmbientLightAwareDlg.cpp. Uncomment the following #include lines: C++ #include "AmbientLightAwareSensorEvents.h" #include "AmbientLightAwareSensorManagerEvents.h" 24. Navigate to the AmbientLightAwareDlg constructor. Uncomment the initialization of m_psensormanagerevents and m_lflogfont class members. 25. Uncomment CleanUp(). This method will be called when shutting down. 10

11 26. Uncomment InitAmbientLightAware(). This method will be called on startup to perform sensorrelated initializations. 27. Navigate to OnInitDialog(), and uncomment the call to InitAmbientLightAware(). 28. Uncomment UpdateLux(). This method determines the appropriate font size for the current illumination. It updates UI members (number of sensors an average luminance) and updates the UI. A proper application might implement low-pass filtering to avoid too frequent font updates that might irritate the user. 29. Navigate to OnPaint(), uncomment the code that changes the font for the IDC_STATIC_SAMPLE static control. 30. Navigate to the top of AmbientLightAware.cpp. Uncomment the following #include lines: (C++) #include "AmbientLightAwareSensorEvents.h" #include "AmbientLightAwareSensorManagerEvents.h" 31. Navigate to InitInstance(). Uncomment calls to CoInitializeEx(), CoUninitialize() and dlg.cleanup(). 32. Compile and run the application. Change illumination value and see text grow and shrink. 11

12 Summary In this lab, you have experimented with the Windows 7 Sensor API by integrating sensor support into an existing application. Integrating a production-quality application with Windows 7 Support might require slightly more work than you have done in this lab, but you are now sufficiently prepared to begin this quest on your own. 12