== Overview == This is a tutorial for installing and using Sensor Actuator Gateway (SAG v.3.0.2) application and Resource End-Point (REP v.2.7) for Google Android devices. The first chapter is a guide for installing both SAG and REP which is organized as connected steps. The second chapter is a quick tutorial for using SAG and REP which are both provided with a control-panel for an Android device. Keep in mind that the SAG is required to run and use the REP. The system overview is shown below: [[Image(repsag.jpg, 480px,center)]] [[PageOutline(2-3,Table of Contents,inline)]] == Requirements == Here is a list of requirements for these two program: * Android operating system v1.5+ * 100 KB space on the SD-card used for SAG cache and REP data (required) * Enabled GPS satellites or wireless network location determination (optional) * Wireless network access using Wi-Fi or Mobile network (required) * Note that REP requires an open port in the wireless network connection firewall * SAG v.3.0.2 supports Accelerometer, Temperature, Magnetic-field and Orientation sensors * Information about sensor types available on: http://developer.android.com/reference/android/hardware/SensorEvent.html == Installation Guide == There are five connected steps which guide you for installing the SAG and REP. Try to complete each step before moving to the next one. === Step 1: Preparation === Before downloading and installing android package files, make sure that these steps are done: * Both SAG and REP use some files and folders on the SDcard. * → All paths and file types are configurable on the properties file, but note that for a simple installation and first run, it is required to remove all files and folders under /sdcard/ericsson/sag/ and /sdcard/ericsson/rep/ folders. * Make sure that wireless network access is enabled on your device. The REP is working with both {{{WiFi}}} and Mobile network, but it is required to have an open port in the wireless network connection firewall. The default port which is setup during the installation is 8182. You can change this port later in the properties file or using the control panel which is explained on the second chapter of this tutorial. * Enable a location resource on your device (GPS satellites or wireless network location determination). This is an optional requirement which enables SAG to provide location data. In most Android devices, this setting is under Settings>Location>{{{UseWirelessNetwork}}} and Settings>Location>EnableGPSsatellites * Both SAG and REP are unsigned and non-market applications. It is required to enable installation of “unknown source application” which is found under Settings>Application>{{{UnknownSources}}} * If you have installed these applications before, it is required to uninstall them in order to have a clean installation. * There are two android package file (.apk) which should be installed: “sag.apk” is the SAG and “rep.apk” is the REP program package file. Follow from Step 2 for installing these two packages. === Step 2: Installing the SAG === There are different ways to install an Android package file. First you should have the “sag.apk” which is the SAG application. You can install this package using the Android Debug Bridge which you can find about it on http://developer.android.com/guide/developing/tools/adb.html web-page. There are other ways which are explained in http://www.talkandroid.com/guides/install-apk-files-on-android/ and http://androidcommunity.com/forums/f12/how-to-install-an-apk-7588/ pages. But the easiest way is to download the "AppInstaller" application from the Android Market and install the package from the device's SDcard which is explained below: * Go to the Android Market and search for a installer which is capable of installing APK files from SDcard. There are many free applications available on the Android's Market now. These applications use the Android's installer, which some file managers can do that also. * Copy the “sag.apk” to the device's SDcard, somewhere that you can find later. * Use the application installer and select the file and install the SAG. * Proceed to Step 3. === Step 3: Setting up the SAG (first time run) === SAG needs to prepare the files and folders that it will use. When you run the SAG for the first time, it creates all files and folders. Follow these steps: * Run the SAG * Now you should be able to see the SAG v.x.x Control Panel. * The Control Panel is simple and on top you will see the log information. * SAG tries to create a default properties file which is editable on the Control Panel * You should be able to see the Control Panel as shown in this picture: [[Image(control-panel.png, center)]] You can see that a new properties with default values is created. * If any problem occurs, you will see the proper message in the log area. In that case, try to follow the steps until now again to find the solution. * SAG is ready. For moving to the next step and installing REP, we (optionally required) can let the SAG be running so that you won't receive any warning while installing the REP. To do so, You should start the SAG service by pressing the menu key on the device and selecting “Start SAG Service” option on the control panel. Now you should be able to see the “Sensor Actuator Gateway” on your device's notification bar. * After starting the SAG service, we want to hide the control panel and proceed to install the REP. Press the menu key on the device and select “Hide The Control Panel” option. In case that you want to exit the SAG for any reason, you can select the “Stop the service & exit” option and start the SAG again later. * Now you can proceed to install the REP === Step 4: Installing the REP === You can follow the same steps as installation of SAG for the REP. The most simple way is: * First you should have the “rep.apk” copied to the device's SDcard. * Use the installer application from the Android Market select the “rep.apk” file and install it. * Proceed to Step 5. === Step 5: Setting up the REP (first time run) === REP also needs to prepare the files and folders that it will use. But it is a bit different as you did when installing the SAG. Follow these steps: * Run the REP * At first you will see a notification, titled “properties not found” and asks to create the properties file on “/sdcard/ericsson/rep/repProperties”. Select “Yes”. * Now you will see a screen like this: [[Image(properties.png, center)]] As you can see, in the log area it is mentioned that the properties is created. * Now you should exit the REP before start using it. Press the menu key on the device and select “Exit” option. * Later, if you start the REP again, you shouldn't see any notification to create the properties file. * Installation is complete! Just keep in mind that SAG service is required to run the REP, which means SAG's service should be started first, and then run the REP. * Done! Both SAG's and REP's control panels are simple to use. Next chapter has more information about it. == Using Android-SAG and Android-REP == n this chapter you can find how to use the SAG and REP. Most of the features are accessible and configurable on the control panel. Each application uses a properties file which is also editable from control panels. === Android SAG === The Android SAG is a Sensor Actuator Gateway which collects the data from Android's device sensors and provide them in OGC SWE Observation and Measurements (O&M) format (http://www.opengeospatial.org/standards/om). It also provides a description for each sensor in Sensor Model Language format (http://www.opengeospatial.org/standards/sensorml). This information will be used by a REP. When you start the SAG, The control panel (CP) will be launched. On top of the CP you can find the log information which shows the current status of the SAG service. On the bottom of the CP, there is an {{{EditText}}} which contains the properties file contents. By pressing the menu button on your android device, you will access to several operational options. Running the SAG will NOT start the SAG service. To do so, press menu and select the “Start SAG Service” option. The SAG service can be started from other Android applications or services also. But the CP is the easiest way. The SAG service will be running on background. This means that you can hide (exit) the CP and keep the service running. This is possible by pressing menu and selecting “Hide the Control Panel” option. In this case, when ever you run the SAG again, the CP will connect to the running SAG service. In order to check the O&M data, you can press menu and select “All Data” option. This will show the observation of all of the sensors on the bottom of the CP. The O&M data is an XML data which is not really useful to see them on the log area! So this option is just to control whether the SAG is producing the data or not. If not, then you will see “NA”. Similarly, the descriptions are observable by pressing menu and selecting “Description” option. At the bottom of the CP, the properties file contents are accessible. Here is information about each item on it: * {{{MaxCacheSize=50}}} * This is an option for defining the maximum size of the cache for each sensor. SAG keeps the sensor data in a cache file and provide them as a group observation in O&M format. This option indicates the cache size which affects the response time of SAG. The best choice for this item is between 10 and 50. more than 100 is not required. * {{{CacheCleanupAmount=20}}} * The cache manager remove this amount of items every time the cache exceeds the maximum number. Smaller number makes the manager more busy and bigger number may cause read and write latencies. On a max 50 size, the number 20 is the best. * {{{DescriptionPrefix=SML}}} * This is the actual file name prefix for sensor descriptions which is stored on the SD-card * {{{DescriptionSuffix=xml}}} * The description file suffix (xx.xml) – this can be useful if later you want to check the SensorML format description files. * {{{DataPrefix=DATA}}} * Data file prefix * {{{DataSuffix=txt}}} * Data file prefix – the file content are not useful to observe * {{{EverNTime=40}}} * This is a number to increase/decrease the speed of updating data or decrease/increase the weight of the app. The choice 40 is sufficient and has been tested in different devices. * {{{CachePath=/sdcard/ericsson/sag/cache}}} * The actual path of the cache on the SD-card. Using the phone's memory is not required. Note that this properties file is created using Java Properties. As long as we use the SAG for the REP, all the default options are the best case for REP and not recommended to change in case that you made any change to the properties file, you should save it also. Press menu and select “Save Properties” option. Then you should restart the SAG in order to have the changes. For stopping the SAG service completely, press menu and select “Stop the Service and Exit” option. In case that you made a change in the properties file and you started receiving errors, you should double check the properties file. Otherwise delete the /sdcard/ericsson/sag/ folder contents and start over again. When the SAG service is running, there will be an item on the device's notification bar, titled as “Sensor Actuator Gateway”. There you can see if the service is running or not. === Android REP === The Android REP is a Resource End-Point, designed with the same specifications as REPv2. This application collects the data from Android SAG, which means SAG service should be running before starting the REP. After installing the REP and the first run which sets up the REP folders and files, the application will be ready to use. Android REP consists of a background service and a control-panel (R-CP). By starting the REP, the R-CP starts and checks the status of the system and then it starts the REP service. When the REP service starts, there will be a notification titled as “Resource End-Point” in the notification bar of the device. If any problem occurs, it will be shown in the notification bar. As I mentioned in the preparation step, the wireless network access should be enabled on your device. The most common problem that might occur is that the port which is used by REP may not be open. Just make sure that the port is open in the wireless network connection firewall. The default port that is used is 8182 and it is configurable in the properties file. Before introducing the R-CP, I will explain the elements on the properties file: * {{{RPIexpirationMinutesUpToOneDay=1200}}} * This option is used to set the expiration time of REP's description which will be published to the Resource Directory. This number can range from 1 to 1439 (up to one day). The value is in “minutes”. If you wanted to have a static or longer expiration period, use the next option. This option is used only in case that the next option is set to 0. * {{{RPIexpirationDate=0}}} * This is the expiration date of a description which is published to the Resource Directory. The format of this option is same as the standard format of Resource Description. (for example 10-04-01T15:30:00+01:00) But note that this option is generated by Java properties, which means: if you wanted to make any change for this option using the R-CP or a text editor, you should take care of Java properties style formats. For example for a “:” sign, you should use “\:” instead. An example can be: 10-04-01T15\:30\:00+01\:00 . If you want to use the previous option to set the expiration time dynamically, then set this option to 0. * {{{ResDescRegistrationPeriod=50000000}}} * This option sets the period that Android REP publishes its description to the Resource Directory and it is in milliseconds. As a sample scenario, lets say that the first option (RPIexpirationMinutesUpToOneDay) has been set to 1200 minutes. By having a 50000000 value for this option, REP re-publish the description after about 833 minutes (50000000 milliseconds) to the Resource Directory. This doesn't mean that these two are directly related to each other, but it means that we publish the description to the Resource Directory a while before the previous one is expired. * {{{RepPort=8182}}} * The port that REP uses (should be open through firewalls) keep in mind that if the network interface changes (for example from Wi-Fi to GPRS), this port should be also open to the new interface. Also same thing with hosts. * {{{RDRef=/rpi}}} * The RPI of the Resource Directory. It will be used with the next option (RDHost) * {{{RDHost=173.1.81.228\:8184}}} * This option locates the Resource Directory host (without the reference). This will include ONLY the ip address and the port number. The protocol should NOT be used here (http://173.1.81.... is wrong!). Also the same thing happens with saving a java properties file when indicating the port number. It means that there will be a “\” before “:”. so if the ip address and the port number is 173.1.81.228:8184, You should write 173.1.81.228\:8184 … a better example is that if the RD is located on http://173.1.81.228:8184/rpi then you should only write 173.1.81.228\:8184 * {{{RDHost4=resource-directory.appspot.com}}} * if you have some extra IP address of other hosts that can be used, you can just write them here on the properties file using a name that is not used by other options (RDHost4 is just a random name – you can even remove all of these options) * {{{resetSubsFile=0}}} * This is used when you want to reset the subscribers information when you exit from the REP. If you use 0 for this option, all of the subscribers information will be save and restored after running the REP again. But if you use 1, then every time you exit the REP, the subscriber's file will be cleared. * {{{RepRoot=/rep}}} * Defining where the REP root is located: for example, if the ip address of your device is 192.36.158.30 and the port number has been set to 8182, using this option with “/rep” value sets the REP location on //192.36.158.30:8182/rep and a temperature sensor will be available on http://192.36.158.30:8182/rep/sensor/Temperature * {{{MinSubscPeriod=2000}}} * This option is the time in milliseconds which defines the general duration of service delays in between data provision for subscribers. This will put a minimum period for providing data for a subscriber. So for example if this option is set to 2000 milliseconds and a subscriber requests for data in every 10 millisecond, then the REP will send the data only every 2000 milliseconds. This will affect the efficiency of the application. * {{{mngSubsc=5}}} * this is a complementary option for the previous option. In the example that a subscriber asks for data with a very small period, the REP only sends the data to that subscriber with its own {{{MinSubscPeriod}}} duration. But in every interval, in can provide a number of data for that subscriber. For example, having a value 5 for this option means that after the {{{MinSubscPeriod}}}, there will be 5 posts of data from the REP to that subscriber based on its request. Changing this value requires a good understanding about the scenario. Otherwise don't modify this option. This value can range from 1 to 10. A value more than 10 can cause long latencies with the service for subscribers. * {{{DTAPath=/sdcard/ericsson/rep/dta/}}} * The path that REP use to store its settings on the SD-card * {{{SubscFile=subscribers}}} * The subscriber's file name. This is used by REP and the contents should NOT be modified. The Android REP Control Panel (R-CP) shows all of the settings and behavior that the REP service has. At top of the R-CP screen, you can find the REP Location. If you are moving around with your device and the network host or interfaces changes, you need to refresh this manually. For doing so, press menu and select “Refresh REP Location” option. If there will be any problem, you will also see the appropriate message. Keep in mind that when you start the REP, you are required to be connected to a network. But later (while running) it is okay to go out of network range. In the middle of the R-CP screen, the log is located (with a dark blue background) and almost all of the necessary information is shown there. If you want to check the status of the REP service, press menu and select “View REP Status” option. Then you will see information about loading properties, connection to SAG, availability of REP, subscriber's service status and the description provider which publishes the description to a Resource Directory. You can also see a list of subscribers by pressing menu and selecting “View Subscribers” option. At the bottom of the R-CP screen (in the scrollable area), you can find a {{{EditText}}} area where the properties file is displayed. In case that you made any changes, you should save and restart the REP by pressing menu and selecting “Save properties and exit” option. If you are using a device with a keyboard (like T Mobile G1) then opening the keyboard will cause the rotation of the screen that sometimes may cause problems with the R-CP. In this case you should exit the program and run it again.