This documentation is for WSO2 IoT Server 3.0.0. View the documentation for the latest release.
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
Android - IoT Server 3.0.0 - WSO2 Documentation
IoT Server 3.0.0
Expand all   Collapse all
                                                                                                                                                                                                                                                                                                                                                                                                 
||
Skip to end of metadata
Go to start of metadata

WSO2 IoTS supports devices on Android version 4.2.x to 7.0 (Android Jelly Beans to Nougat). The following subsections explain how you can enroll your own device with WSO2 IoT Server and start using it. 

 

Enroll an Android device

Follow the instructions given below to enroll an Android device:

  1. Sign in to the Device Management console.

     Click here for more information.
    Follow the instructions below to sign into the IoTS device management console:

    1. Start the server.

    2. Access the device management console.

      • For access via HTTP: 
        http://<HTTP_HOST>:9763/devicemgt/ 

        For example: http://localhost:9763/devicemgt/
      • For access via secured HTTP: 
        https://<HTTPS_HOST>:9443/devicemgt/ 
        For example: https://localhost:9443/devicemgt/ 

    3. Enter the username and password, and sign in.

      The system administrator will be able to log in using admin for both the username and password. However, other users will have to first register with IoTS before being able to log into the IoTS device management console. For more information on creating a new account, see Registering with IoTS.

    4. Click LOGIN. The respective device management console will change, based on the permissions assigned to the user.
      For example, the device management console for an administrator is as follows:

  2. Click Enroll New Device.
  3. Click Android to enroll your device with WSO2 IoTS.
  4. Enroll the device.
    1. Click Enroll Device.

    2. Scan the QR code to download the Android agent onto your Android device.

      You need to make sure that your Android device and the IoT Server are on the same network, else you will not be able to download the Android agent.

      After scanning the QR code you will be directed to a web page. When this page appears, the web browser will typically display an "insecure connection" message, which requires your confirmation before you can continue.

       Click here for more information.

      The WSO2 IoTS consoles are based on the HTTPS protocol, which is a combination of HTTP and SSL protocols. This protocol is generally used to encrypt the traffic from the client to server for security reasons. The certificate it works with is used for encryption only, and does not prove the server identity, so when you try to access these consoles, a warning of untrusted connection is usually displayed. To continue working with this certificate, some steps should be taken to "accept" the certificate before access to the site is permitted. If you are using the Mozilla Firefox browser, this usually occurs only on the first access to the server, after which the certificate is stored in the browser database and marked as trusted. However, with other browsers, the insecure connection warning might be displayed every time you access the server.

      This scenario is suitable for testing purposes, or for running the program on the company's internal networks. If you want to make these consoles available to external users, your organization should obtain a certificate signed by a well-known certificate authority, which verifies that the server actually has the name it is accessed by and that this server belongs to the given organization.

  5. Click Download Android Agent.

  6. Open the downloaded file, and tap INSTALL.

  7. Tap OPEN, once the WSO2 Android Agent is successfully installed.

  8. Tap Skip and go to Enrollment to proceed with the default Android enrollment process.
    If you want to set up the work profile and enable data containerization, click Setup Work-Profile .

  9. Enter the server address based on your environment, in the text box provided. A confirmation message will appear.

    • Developer Environment - Enter the server IP as your server address.
      Example: 10.10.10.123:8280

    • Deployment Environment - Enter the domain as your server address.

      The Android Agent app's default port is 8280. If you are using any other port, the server address should state the new port in the following format: www.abc.com :<PORT>
      For example, if the port is 8289 the server IP is as follows: www.abc.com:8289

  10. Tap Yes to continue.
  11. Enter your details and tap Register. A confirmation message will appear.

    • Username - Enter your WSO2 IoTS username.

    • Password - Enter your WSO2 IoTS password. 

    • Domain - Enter the domain only if the server is hosted with multi-tenant support.
    • Ownership type - Select the corresponding device ownership option. This will customize the device management behavior accordingly.
      • BYOD - Bring your own device.
      • COPE - Corporate owned personally enabled.
  12. Tap Yes to continue.

    • If you select BYODgo to step 13 - You will be shown a policy agreement, which you can either accept or reject.

      You will get access to WSO2 IoTS only if you accept the policy agreement.

    • If you select COPEgo to step 17 - As it's a corporate owned device, you will not be shown a policy agreement. You will have to adhere to the company policy.
  13. Read the tenant policy agreement, and tap Agree to accept the agreement.  

  14. Tap ALLOW to allow the WSO2 Android agent to make and manage phone calls, access photos, media, and files, and access the device location respectively.

    You will get this message only if your Android OS is Marshmallow (6.0) or above.

    Example:

  15. Set a PIN code of your choice with a minimum of 4 digits. The PIN code will be used to secure your personal data. Thereby, the IoT server will not be able to carry out critical operations on your personal data without using this PIN. 
    Example: If the device management admin needs to wipe your device or remove data from the device, he/she can not directly wipe it without the PIN code. You have to provide the PIN code to get your device wiped or you can log into the device management console and wipe your device by entering the PIN code. A confirmation message will appear.

    You will be prompted to provide a PIN code only if your device is a BYOD device.

  16. Confirm the PIN and click OK to continue.
  17. Tap ACTIVATE to enable the WSO2 agent administrator on your device. A confirmation message will appear after enabling the device admin.

  18. You have now successfully registered your Android device. If you wish to unregister the registered device, click Unregister.

     Click here for more information on how to uninstall the Android agent.

    Follow the instructions below to uninstall the Android agent app:

    1. Open the Android agent application and click Unregister.

    2. In Settings, tap Applications or Application Manager on your device. This may differ based on your device. If your device has the Applications menu, tap Manage Applications, otherwise directly move to step 3.

    3. Tap WSO2 Agent to select the Android agent app.

    4. Tap Uninstall.

Prerequsite

Configure the email settings to send out an invitation for users to register their device with WSO2 IoTS.

 Click here for more information on configuring the email settings.

In WSO2 IoTS, user registration confirmation emails are disabled by default, and the admin needs to provide the required configuration details to enable it.

  1. Create an email account to send out emails to users that register with IoT Server (e.g., [email protected]).

  2. Open the <IOTS_HOME>/repository/conf/axis2/axis2.xml file, uncomment the mailto transportSender section, and configure the IoTS email account.

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
   <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
   <parameter name="mail.smtp.port">587</parameter>
   <parameter name="mail.smtp.starttls.enable">true</parameter>
   <parameter name="mail.smtp.auth">true</parameter>
   <parameter name="mail.smtp.user">synapse.demo.0</parameter>
   <parameter name="mail.smtp.password">mailpassword</parameter>
   <parameter name="mail.smtp.from">[email protected]</parameter>
</transportSender>

    For mail.smtp.from, mail.smtp.user, and mail.smtp.password, use the email address, username, and password (respectively) from the mail account you set up.

    Example:

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
   <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
   <parameter name="mail.smtp.port">587</parameter>
   <parameter name="mail.smtp.starttls.enable">true</parameter>
   <parameter name="mail.smtp.auth">true</parameter>
   <parameter name="mail.smtp.user">foo</parameter>
   <parameter name="mail.smtp.password">$foo1234</parameter>
   <parameter name="mail.smtp.from">[email protected]</parameter>
</transportSender>

  3. Optionally, configure the email sender thread pool.
    Navigate to the email-sender-config.xml file, which is in the <IOTS_HOME>/repository/conf/etc directory, and configure the following fields under <EmailSenderConfig>.

    • MinThreads: Defines the minimum number of threads that needs to be available in the underlying thread pool when the email sender functionality is initialized.

    • MaxThreads: Defines the maximum number of threads that should serve email sending at any given time.

    • KeepAliveDuration: Defines the duration a connection should be kept alive. If the thread pool has initialized more connections than what was defined in MinThreads, and they have been idle for more than the KeepAliveDuration, those idle connections will be terminated

    • ThreadQueueCapacity: Defines the maximum concurrent email sending tasks that can be queued up.

    Example:

    <EmailSenderConfig>
   <MinThreads>8</MinThreads>
   <MaxThreads>100</MaxThreads>
   <KeepAliveDuration>20</KeepAliveDuration>
   <ThreadQueueCapacity>1000</ThreadQueueCapacity>
</EmailSenderConfig>

  4. Optionally, customize the email templates that are in the <IOTS_HOME>/repository/resources/email-templates directory. 

    The email template functionality of WSO2 IoT Server is implemented on top of Apache Velocity, which is a free and open-source template engine.

    1. Open the email template that you wish to edit based on the requirement, such as the user-invitation.vm or user-registration.vm file.
    2. Edit the <Subject> and <Body> to suite your requirement.
    3. Restart WSO2 IoT Server.

    If you need to access HTTP or HTTPS base URLs of the server within your custom template configs, use the $base-url-http and $base-url-https variables, respectively

  1. Sign in to the Device Management console.

     Click here for more information.
    Follow the instructions below to sign into the IoTS device management console:

    1. Start the server.

    2. Access the device management console.

      • For access via HTTP: 
        http://<HTTP_HOST>:9763/devicemgt/ 

        For example: http://localhost:9763/devicemgt/
      • For access via secured HTTP: 
        https://<HTTPS_HOST>:9443/devicemgt/ 
        For example: https://localhost:9443/devicemgt/ 

    3. Enter the username and password, and sign in.

      The system administrator will be able to log in using admin for both the username and password. However, other users will have to first register with IoTS before being able to log into the IoTS device management console. For more information on creating a new account, see Registering with IoTS.

    4. Click LOGIN. The respective device management console will change, based on the permissions assigned to the user.
      For example, the device management console for an administrator is as follows:

  2. Click Invite by Email.
  3. Enter the email address of the users who need to enroll their device with WSO2 IoTS, and click Send Invite(s).
    If you entered your email address, you will receive the registration email.
  4. Click on the link in the email to download the Android agent.

  5. Click Download Android Agent.

  6. Open the downloaded file, and tap INSTALL.

  7. Tap OPEN, once the WSO2 Android Agent is successfully installed.

  8. Tap Skip and go to Enrollment to proceed with the default Android enrollment process.
    If you want to set up the work profile and enable data containerization, click Setup Work-Profile .

  9. Enter the server address based on your environment, in the text box provided. A confirmation message will appear.

    • Developer Environment - Enter the server IP as your server address.
      Example: 10.10.10.123:8280 

    • Deployment Environment - Enter the domain as your server address.

      The Android Agent app's default port is 8280. If you are using any other port, the server address should state the new port in the following format: www.abc.com :<PORT>
      For example, if the port is 8289 the server IP is as follows: www.abc.com:8289

  10. Tap Yes to continue.
  11. Enter your details and tap Register. A confirmation message will appear.

    • Username - Enter your WSO2 IoTS username.

    • Password - Enter your WSO2 IoTS password. 

    • Domain - Enter the domain only if the server is hosted with multi-tenant support.
    • Ownership type - Select the corresponding device ownership option. This will customize the device management behavior accordingly.
      • BYOD - Bring your own device.
      • COPE - Corporate owned personally enabled.
  12. Tap Yes to continue.

    • If you select BYODgo to step 13 - You will be shown a policy agreement, which you can either accept or reject.

      You will get access to WSO2 IoTS only if you accept the policy agreement.

    • If you select COPEgo to step 17 - As it's a corporate owned device, you will not be shown a policy agreement. You will have to adhere to the company policy.
  13. Read the tenant policy agreement, and tap Agree to accept the agreement.  

  14. Tap ALLOW to allow the WSO2 Android agent to make and manage phone calls, access photos, media, and files, and access the device location respectively.

    You will get this message only if your Android OS is Marshmallow (6.0) or above.

    Example:

  15. Set a PIN code of your choice with a minimum of 4 digits. The PIN code will be used to secure your personal data. Thereby, the IoT server will not be able to carry out critical operations on your personal data without using this PIN. 
    Example: If the device management admin needs to wipe your device or remove data from the device, he/she can not directly wipe it without the PIN code. You have to provide the PIN code to get your device wiped or you can log into the device management console and wipe your device by entering the PIN code. A confirmation message will appear.

    You will be prompted to provide a PIN code only if your device is a BYOD device.

  16. Confirm the PIN and click OK to continue.
  17. Tap ACTIVATE to enable the WSO2 agent administrator on your device. A confirmation message will appear after enabling the device admin.

  18. You have now successfully registered your Android device. If you wish to unregister the registered device, click Unregister.

     Click here for more information on how to uninstall the Android agent.

    Follow the instructions below to uninstall the Android agent app:

    1. Open the Android agent application and click Unregister.

    2. In Settings, tap Applications or Application Manager on your device. This may differ based on your device. If your device has the Applications menu, tap Manage Applications, otherwise directly move to step 3.

    3. Tap WSO2 Agent to select the Android agent app.

    4. Tap Uninstall.

  1. Sign in to the Device Management console.

     Click here for more information.
    Follow the instructions below to sign into the IoTS device management console:

    1. Start the server.

    2. Access the device management console.

      • For access via HTTP: 
        http://<HTTP_HOST>:9763/devicemgt/ 

        For example: http://localhost:9763/devicemgt/
      • For access via secured HTTP: 
        https://<HTTPS_HOST>:9443/devicemgt/ 
        For example: https://localhost:9443/devicemgt/ 

    3. Enter the username and password, and sign in.

      The system administrator will be able to log in using admin for both the username and password. However, other users will have to first register with IoTS before being able to log into the IoTS device management console. For more information on creating a new account, see Registering with IoTS.

    4. Click LOGIN. The respective device management console will change, based on the permissions assigned to the user.
      For example, the device management console for an administrator is as follows:

  2. Click Download APK.
  3. Copy the downloaded file to your mobile device.

  4. Open the file, and tap INSTALL.

  5. Tap OPEN, once the WSO2 Android Agent is successfully installed.

  6. Tap Skip and go to Enrollment to proceed with the default Android enrollment process.
    If you want to set up the work profile and enable data containerization, click Setup Work-Profile .

  7. Enter the server address based on your environment, in the text box provided. A confirmation message will appear.

    • Developer Environment - Enter the server IP as your server address.
      Example: 10.10.10.123:8280 

    • Deployment Environment - Enter the domain as your server address.

      The Android Agent app's default port is 8280. If you are using any other port, the server address should state the new port in the following format: www.abc.com :<PORT>
      For example, if the port is 8289 the server IP is as follows: www.abc.com:8289

  8. Tap Yes to continue.
  9. Enter your details and tap Register. A confirmation message will appear.

    • Username - Enter your WSO2 IoTS username.

    • Password - Enter your WSO2 IoTS password. 

    • Domain - Enter the domain only if the server is hosted with multi-tenant support.
    • Ownership type - Select the corresponding device ownership option. This will customize the device management behavior accordingly.
      • BYOD - Bring your own device.
      • COPE - Corporate owned personally enabled.
  10. Tap Yes to continue.

    • If you select BYODgo to step 11 - You will be shown a policy agreement, which you can either accept or reject.

      You will get access to WSO2 IoTS only if you accept the policy agreement.

    • If you select COPEgo to step 15 - As it's a corporate owned device, you will not be shown a policy agreement. You will have to adhere to the company policy.
  11. Read the tenant policy agreement, and tap Agree to accept the agreement.  

  12. Tap ALLOW to allow the WSO2 Android agent to make and manage phone calls, access photos, media, and files, and access the device location respectively.

    You will get this message only if your Android OS is Marshmallow (6.0) or above.

    Example:

  13. Set a PIN code of your choice with a minimum of 4 digits. The PIN code will be used to secure your personal data. Thereby, the IoT server will not be able to carry out critical operations on your personal data without using this PIN. 
    Example: If the device management admin needs to wipe your device or remove data from the device, he/she can not directly wipe it without the PIN code. You have to provide the PIN code to get your device wiped or you can log into the device management console and wipe your device by entering the PIN code. A confirmation message will appear.

    You will be prompted to provide a PIN code only if your device is a BYOD device.

  14. Confirm the PIN and click OK to continue.
  15. Tap ACTIVATE to enable the WSO2 agent administrator on your device. A confirmation message will appear after enabling the device admin.

  16. You have now successfully registered your Android device. If you wish to unregister the registered device, click Unregister.

     Click here for more information on how to uninstall the Android agent.

    Follow the instructions below to uninstall the Android agent app:

    1. Open the Android agent application and click Unregister.

    2. In Settings, tap Applications or Application Manager on your device. This may differ based on your device. If your device has the Applications menu, tap Manage Applications, otherwise directly move to step 3.

    3. Tap WSO2 Agent to select the Android agent app.

    4. Tap Uninstall.


Try it out

You can view device details and carry out operations on your device, after successfully enrolling it with WSO2 IoTS. Let's take a look at how you can do it:

  1. Navigate to the Device Management page to view all the created devices.

     Click here for more information on navigating to the Device Management page.
    1. Sign in to the Device Management console.
    2. Click the menu icon.
    3. Click Device Management.

  2. Click the view icon on the Android device you enrolled.
    Example:

  3. You will be directed to the device details page where you can view the device information and try out operations on a device.
    Example:

     View device details

    The details of each registered devices will be shown on separate pages within the Device page.


    		Description
    Device Details

    The following device information will be retrieved automatically when you register with IoTS.

    DeviceThis shows the name the user has given his/her device (e.g., Kim's iPhone).
    OwnershipIndicates if the device is your own device/Bring Your Own Device (BYOD) or if it's a Corporate-Owned, Personally Enabled (COPE) device.
    For the device to be a COPE device, WSO2 IoT Server must be configured to use the system server application.
    StatusIndicates if the device is active, inactive or removed from WSO2 IoTS.
    Policy ComplianceIf your device does not comply with certain criteria in the enforced policy, the aspects in which your device is none compliant will be highlighted under this section.
    Device LocationProvide the location of your device.
    Installed ApplicationA list of all the applications that have been installed on your device and the memory consumption by each application will be listed under this section.
    Operation LogA list of all the operations that have been carried out by you and its current status
     Device operations

    The default operations that are available for Android devices are accessible for BYOD devices. The COPE devices can only be carried if you have integrated the Android system service application with WSO2 IoT Server. This enables you to have better control over the devices registered with WSO2 IoT Server.

    Click on the operation you wish to carry out and provide the required details (if requested) to apply the selected operation on your device.

    OperationDescription
    Device Lock
    		Ability to lock a device via the IoT Server.
    Device Unlock
    		Ability to unlock the device via the IoT Server
    Location
    		Ability to receive the location of the device.
    Mute Device
    		Ability to enable the silent profile on a device via the IoT Server.
    Enterprise Wipe
    		Ability to unregister a device from IoTS.
    Clear Password
    		Ability to remove a device lock via the IoT Server.
    Change Lock-Code
    		Ability to change the provided passcode or lock-code.
    Ring
    		Ability to ring the device via the IoT Server.
    Message
    		Ability to send a message to the device via the IoT Server. The IoTS admin can use
    this device operation to send group messages or even private messages to the IoTS users.
    Wipe Data
    		Ability to carry out a factory reset operation on your own device via the IoT Server. The user will have
    to provide the PIN, which he/she entered when registering to IoTS, to be able to wipe his/her device.
    Reboot
    		Ability to reboot or restart your Android device.
    Upgrade Firmware

    Ability to upgrade the firmware to a newer version, over-the-air (OTA)

    For more information, see Upgrading Firmware of an Android Device.

    Logcat
    		Ability to push logcat of the device to the analytics server. Logcat displays messages in real time and keeps a history so you can view the old messages.

    System service application operations

    WSO2 IoT Server provides a separate service application that can be signed by a firmware signing key and installed on the devices as a system application alongside the Android agent application. This enables you to have better control over the devices registered with WSO2 IoT Server. To install the system service application on the devices, you need to integrate it with WSO2 IoT Server. For more information, see Integrating the Android System Service Application.

    You can perform the operations listed above and the operations listed below on your COPE device if you have the system service application installed on your Android device.

    • Schedule firmware upgrades on the device.
    • Reboot or restart your device.
    • Install and update applications in silent mode that is without the user's confirmation via the system service application.
    • Hard lock an Android device, where the Administrator permanently locks the device.
    • Unlock a device that was hard locked.
  • No labels
||