diff --git a/gsg-gtk.md b/gsg-gtk.md new file mode 100644 index 0000000..428e3a1 --- /dev/null +++ b/gsg-gtk.md @@ -0,0 +1,208 @@ +![IoTivity logo](/Images/IoTivity-logo.png) + +[**Getting Started**](index.md) | [**Getting Started FAQ**](getting-started-faq.md) | [**Digging Deeper**](digging-deeper.md) | [**GitHub Repository**](https://github.com/iotivity/iotivity-lite) | [**IoTivity.org**](https://iotivity.org) + +This guide will show you how to download, build, and run two simulated devices on the same Linux PC: + +- The *server*, a GUI app in this case, simulates a smart home dimmable light. The switch and dimmer can be adjusted from the server GUI. This simulates a physical dimming light switch. +- The *client*, a GUI app, controls the smart device. The client typically runs on a smart phone. + +The two apps talk to each other over a loopback connection, using the OCF protocol. + +![OCF protocol over loopback connection](/Images/ocfprotocol-loopback-connection.png) + +**To use Windows:** To download, build, and run on a Windows PC instead, check the Iotivity [FAQ](https://wiki.iotivity.org/getting_started_troubleshooting_and_faq). + +## Requirements + +To carry out this tutorial, you will need the following: + +- A Debian-based Linux PC (e.g., Ubuntu), with an internet connection. + +## Install IoTivity and Emulator Sample + +1. On the development PC, open a terminal. + +2. Download source and set up the IoTivity-Lite environment by running this command, which takes several minutes to complete: + + ``` + cd ~ + curl https://openconnectivity.github.io/IOTivity-Lite-setup/install.sh | bash + ``` + + Alternatively, you can download the install.sh script, review and run it from anywhere. + + +3. Install the project scripts: + + + ``` + curl https://openconnectivity.github.io/Project-Scripts/install.sh | bash + ``` + + Rerun this script if an error occurs. + + +4. Install the repository containing emulator sample code. Answer “y” if prompted: + + + ``` + curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash + ``` + + You may need to run source ~/.bashrc or reboot the computer at this point to ensure that your environment variables are set. + + ``` + source ~/.bashrc + + or + + sudo reboot -h now + ``` + +5. Create a project directory: + + ``` + cd ~ + mkdir workspace + cd workspace + ``` + +6. Create the IoTivity project (we'll call it myexample): + + ``` + create_project.sh myexample + cd myexample + ``` + +5. Copy the sample project to the current directory and set it up: + + ``` + cp ~/Emulator-Code/IoTivity-lite/emulator/setup.sh ./ + ./setup.sh + ``` + +The sample project now has all dependencies installed and is ready for code generation and building. + + +## Build and Run the Server App + + +1. Generate code for the server app by running these commands: + + ``` + cd ~/workspace/myexample (if not already there) + gen.sh + ``` + + + This script starts from a default JSON configuration file that can be edited to specify the capabilities of your actual device. The script calls the DeviceBuilder app to generate source code for the server app you’ll run on your smart device (in this case, the dimmable light Emulator app). + +2. Build the server app with this command: + + + ``` + build.sh + ``` + + +3. Reset and run the server app by running these commands: + + + ``` + reset.sh + run.sh + ``` + +A small window should open with a graphical image of a light bulb, an on/off switch and slider dimming switch. + +Leave the terminal window open. The server app is now waiting for commands from the client app, which you’ll install next. + + + +## Build and Run the Client App (If you've already installed OTGC once, you can skip the installation here and jump to step 3.) + +NOTE: Alternatively, you can run the Android version of OTGC on your smart phone or tablet. Get the installation package here: (https://github.com/openconnectivity/otgc-android). You can then just run it and skip the Linux OTGC installation in the steps below. The circle icon will start the discovery process and should find the Emulator server. + +The sample client application is called OTGC (Onboarding Tool and Generic Client). You'll download and build the binary with a script: + +1. On the development PC, open another terminal window. + +2. Download and build the Linux OTGC client by running this command, which takes several minutes to complete: + + ``` + curl https://openconnectivity.github.io/otgc-linux/setup.sh | bash + ``` + + **Troubleshooting:** If the build process finishes but an error occurs, manually run the dpkg command from the setup.sh script. + + ``` + sudo dpkg -i ./otgc-linux/build/debian/out/otgc-2.9.0.deb + #run only in the event of an error and substitute the version of otgc + #that is available at this location (for example, the version number will + #increment as new versions are created (e.g. otgc-2.10.0.deb)) + ``` + +3. Launch the Linux OTGC client by running this command: + + + ``` + /usr/bin/otgc.sh + ``` + + +4. Click to OK the End User License Agreement. + + + OTGC starts and automatically scans all visible OCF devices, listing them in the app's left-hand pane. + + +5. Locate and align both the terminal window that is awaiting incoming connections, plus the app window, so that both are visible. + + + As you proceed with the remaining steps in this section, notice that each action taken in the client app generates console output in the terminal window that had been awaiting incoming connections. This simulates controlling your smart home device with, for example, a mobile phone client: + + + - Click to select the device listed in the left-hand pane, then click the Onboard button. + + + + The Select OTM (Ownership Transfer Method) dialog box pops up. + + + + - Click OK in the Select OTM dialog box. + + + + As device ownership is transferred, the Select OTM dialog box closes and is replaced by the Set Device Name dialog box. + + + - Change the device name, if you wish. Click OK to close the dialog box. + + + - Click to reselect the device in the left-hand pane. + + +6. Onboard (pair) the discovered server by clicking the + icon next to the device. **[Todo OCF: insert screenshot of Linux client screen, callout to + button]** If the item has a gear icon instead of a + icon, it has already been onboarded. You can select the server and click Offboard to prepare to see the onboarding process. + + +8. Once the + icon has changed to a gear, click the gear icon. **[Todo OCF: insert screenshot with callout to gear]** + + +9. In OTGC, find the /binaryswitch and /dimming sections and click the switch value button on the left. **[Todo OCF: insert screenshot /LED section with callout to value button]** The light bulb animation will turn on or off, controlled by the client app over the OCF protocol. Also, the dimming slider will move from 0 to 100. If you change the dimming value (type to get the value accepted), the dimmer slider in the GUI should reflect what you type and the light animation should change. If you type 100, the light should turn on fully and the binary switch should turn on. Notice that the console output in the server terminal also responds to your actions in the client. + + +10. Now “observe” (monitor) the touch buttons on the emulator window in the OTGC app by turning on the "observe" button on the /binaryswitch and /dimmer sections of OTGC, then clicking the switch button or dimming slider on the emulator application. **[Todo OCF: insert screenshot]** Notice that the output in the OTGC app detects the changes in the emulator application. + + +11. Press Ctrl-C in the server terminal or click the "X" in the emulator window to exit the server app. + + +## Digging deeper: Next steps for development + + +Now that you've created a device simulation based on IoTivity, you're read to dig deeper to explore other platforms and learn how to apply IoTivity to your own platform and devices. + + +[**Digging Deeper**](digging-deeper.md) diff --git a/gsg-kit.md b/gsg-kit.md index cdee631..e02adba 100755 --- a/gsg-kit.md +++ b/gsg-kit.md @@ -113,90 +113,73 @@ The steps in this section use SSH. As an alternative, attach a monitor and USB k ![ssh prompt](/Images/ssh-prompt.png) +### Optionally Make Changes to Support Your Location and a Physical Keyboard and Monitor -You’re now ready to install IoTivity code and samples. +1. Before you begin, be sure that the Raspberry Pi is set to use your preferred keyboard. UK English is the Pi’s preset keyboard layout. To choose another keyboard layout: -## Install IoTivity and Pi Samples + ``` + sudo raspi-config #enter the Pi account password, if prompted. + ``` -1. Continuing on your development PC, from the SSH prompt, go to the home directory and install the IoTivity-lite development system, which takes several minutes to complete: +2. In the Raspberry Pi Software Configuration Tool (raspi-config) menu, choose: + * **Localization Options** or **Internationalization Options** + * **Change Keyboard Layout** - ``` - cd ~ - curl https://openconnectivity.github.io/IOTivity-Lite-setup/install.sh | bash - ``` - Alternatively, you can download the install.sh script, review and run it from anywhere. + Select your keyboard and preferred keyboard layout. For example, for American English, after you select your connected keyboard, choose **English (US)**. Navigate through the menus to **save** and **exit** raspi-config. -2. Install the project scripts: + Then reboot with sudo: + ``` + sudo reboot + ``` - ``` - curl https://openconnectivity.github.io/Project-Scripts/install.sh | bash - ``` +You’re now ready to install IoTivity code and samples. - Rerun this script if an error occurs. +## Install IoTivity and Pi Samples -4. Install the repository containing emulator sample code, which takes several minutes to run. Answer “y” if prompted: +1. Continuing on your development PC, from the SSH prompt, go to the home directory and install the IoTivity-lite development system, which takes several minutes to complete: ``` - curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash + cd ~ + curl https://openconnectivity.github.io/IOTivity-Lite-setup/install.sh | bash ``` + Alternatively, you can download the install.sh script, review and run it from anywhere. -5. Build the sample project in a new directory: + +2. Install the project scripts: ``` - cd ~ - mkdir workspace - cd workspace - create_project.sh myproject - cd myproject - cp ~/Emulator-Code/IoTivity-lite/dimming/setup.sh ./ - ./setup.sh - gen.sh - build.sh - reset.sh - run.sh + curl https://openconnectivity.github.io/Project-Scripts/install.sh | bash ``` + Rerun this script if an error occurs. - A GUI light bulb with a switch and slider will appear in the Linux application window. - - -### Set up the Project Environment - - -1. Before you begin, be sure that the Raspberry Pi is set to use your preferred keyboard. UK English is the Pi’s preset keyboard layout. To choose another keyboard layout: +4. Install the repository containing the Raspberry Pi sample code, which takes several minutes to run. Answer “y” if prompted: ``` - sudo raspi-config #enter the Pi account password, if prompted. + curl https://openconnectivity.github.io/Sample-Raspberry-Pi-Code/pi-boards/install.sh | bash ``` + You may need to reboot the Raspberry Pi at this point to ensure that your environment variables are set. -2. In the Raspberry Pi Software Configuration Tool (raspi-config) menu, choose: - - * **Localization Options** or **Internationalization Options** - * **Change Keyboard Layout** - + ``` + sudo reboot -h now + ``` - Select your keyboard and preferred keyboard layout. For example, for American English, after you select your connected keyboard, choose **English (US)**. Navigate through the menus to **save** and **exit** raspi-config. + If you are connected via SSH, you will be disconnected and will have to reconnect when the Pi is booted (a minute is usually enough time) - Then reboot with sudo: - - ``` - sudo reboot - ``` - -3. On the Pi, create a project directory: +5. On the Pi, create a project directory: ``` cd ~ @@ -204,23 +187,23 @@ You’re now ready to install IoTivity code and samples. cd workspace ``` -4. Create the IoTivity project: +6. Create the IoTivity project (we'll call it myexample): ``` create_project.sh myexample cd myexample ``` -5. Copy the sample project to the current directory and set it up: +7. Copy the sample project to the current directory and set it up: ``` cp ~/Sample-Raspberry-Pi-Code/IoTivity-lite/explorer-hat-pro/setup.sh ./ ./setup.sh ``` - If you don't have a HAT board, you can get a sample project with limited functionality. Copy the sample project from this location instead: ~/Sample-Raspberry-Pi-Code/IoTivity-lite/nohat. - -The sample project now has Explorer HAT drivers installed and is ready for code generation and building. + If you don't have a HAT board, you can get a sample project with limited functionality. Copy the sample project from this location instead: ~/Sample-Raspberry-Pi-Code/IoTivity-lite/nohat. (Just substitute "nohat" for "explorer-hat-pro" in the command above) + +The sample project now has Explorer HAT (or no HAT) drivers installed and is ready for code generation and building. ## Build and Run the Server App @@ -229,27 +212,27 @@ The sample project now has Explorer HAT drivers installed and is ready for code 1. On the Pi, generate code for the server app by running these commands: ``` - cd ~/iot-lite/ #or path where you installed IoTivity - ./gen.sh + cd ~/workspace/myexample (if not already there) + gen.sh ``` - This script starts from a default JSON configuration file that can be edited to specify the capabilities of your actual device. The script calls the DeviceBuilder app to generate source code for the server app you’ll run on your smart device (in this case, the Pi). + This script starts from a default JSON configuration file that can be edited to specify the capabilities of your actual device. The script calls the DeviceBuilder app to generate source code for the server app you’ll run on your smart device (in this case, the Pi). NOTE: We run gen.sh from the Project-Scripts directory (it's on the search path) NOT ./gen.sh 2. Build the server app with this command: ``` - ./build.sh + build.sh ``` -3. Reset and run the server app by running these commands: +3. Reset (make the device unowned) and run the server app by running these commands: ``` - ./reset.sh - ./run.sh + reset.sh + run.sh ``` @@ -257,7 +240,9 @@ Leave this terminal window open. The server app is now waiting for commands from -## Build and Run the Client App +## Build and Run the Client App (If you've already installed OTGC once, you can skip the installation here and jump to step 3.) + +NOTE: Alternatively, you can run the Android version of OTGC on your smart phone or tablet. Get the installation package here: (http://dfslfjsdf). You can then just run it and skip the Linux OTGC installation in the steps below. The circle icon will start the discovery process and should find the Raspberry Pi server (make sure you're on the same LAN). The sample client application is called OTGC (Onboarding Tool and Generic Client). You'll download and build the binary with a script: @@ -272,9 +257,9 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client **Troubleshooting:** If the build process finishes but an error occurs, manually run the dpkg command from the setup.sh script. ``` - sudo dpkg -i ./otgc-linux/build/debian/out/otgc-2.9.0.deb - #run only in the event of an error and substitute the version of otgc - #that is available at this location (for example, the version number will + sudo dpkg -i ./otgc-linux/build/debian/out/otgc-2.9.0.deb + #run only in the event of an error and substitute the version of otgc + #that is available at this location (for example, the version number will #increment as new versions are created (e.g. otgc-2.10.0.deb)) ``` @@ -347,7 +332,7 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client **[Todo OCF: This section needs verification and some detail where noted]** -**[It should not be the same example as in the SW Simulation tutorial. It should be device-relevant.] +**[It should not be the same example as in the SW Simulation tutorial. It should be device-relevant. If they have the Explorer Hat, they can observe pressing the buttons] *** diff --git a/gsg-sw.md b/gsg-sw.md index a9e1c1c..42fdd21 100755 --- a/gsg-sw.md +++ b/gsg-sw.md @@ -69,9 +69,9 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client **Troubleshooting:** If the build process completes, but an error occurs, manually run the dpkg command from the setup.sh script. ``` - sudo dpkg -i ./otgc-linux/build/debian/out/otgc-2.9.0.deb - #run only in the event of an error and substitute the version of otgc - #that is available at this location (for example, the version number will + sudo dpkg -i ./otgc-linux/build/debian/out/otgc-2.9.0.deb + #run only in the event of an error and substitute the version of otgc + #that is available at this location (for example, the version number will #increment as new versions are created (e.g. otgc-2.10.0.deb)) ``` @@ -136,21 +136,26 @@ The steps below will show you how to make a simple change to the JSON file, reco 3. Add a dimming resource. The example.json file will now have two resources: binary switch and dimming. ``` - [ - - { - "path" : "/binaryswitch", - "rt" : [ "oic.r.switch.binary" ], - "if" : ["oic.if.baseline", "oic.if.a" ], - "remove_properties" : [ "range", "step" , "id", "precision" ] - }, - { - "path" : "/dimming", - "rt" : [ "oic.r.light.dimming" ], - "if" : ["oic.if.baseline", "oic.if.a" ], - "remove_properties" : [ "range", "step", "value" , "id" , "precision"] - } - ] +[ + { + "path" : "/binaryswitch", + "rt" : [ "oic.r.switch.binary" ], + "if" : ["oic.if.baseline", "oic.if.a" ], + "remove_properties" : [ "range", "step" , "id", "precision" ] + }, + { + "path" : "/dimming", + "rt" : [ "oic.r.light.dimming" ], + "if" : ["oic.if.baseline", "oic.if.a" ], + "remove_properties" : [ "range", "step", "value" , "id" , "precision" ] + }, + { + "path" : "/oic/p", + "rt" : [ "oic.wk.p" ], + "if" : ["oic.if.baseline", "oic.if.r" ], + "remove_properties" : [ "n", "range", "value", "step", "precision", "vid" ] + } +] ``` diff --git a/index.md b/index.md index 17a566a..a6d7187 100644 --- a/index.md +++ b/index.md @@ -16,8 +16,12 @@ These 15-30 minute tutorials walk through installing, building, and using client [**Getting Started with IoTivity (Device Simulation)**](gsg-sw.md) -- Quickly simulates smart device usage by running client and server apps on the same Linux PC, using the OCF protocol to communicate over loopback. +- Quickly simulates smart device usage by running client and command-line server apps on the same Linux PC, using the OCF protocol to communicate over loopback. +[**Getting Started with IoTivity (Graphical Device Simulation)**](gsg-gtk.md) + +- In this example you build a server with a graphical user interface (GUI). The GUI also has a switch and a slider, so you can make changes on the server and observe them in the client. We are still running both the client and the server on the same machine in loopback mode. + [**Getting Started with IoTivity (Raspberry Pi kit)**](gsg-kit.md) - Experience realistic smart device usage with a Raspberry Pi kit ([purchase here](https://openconnectivity.org/developer/developer-kit), under Development Resources and Solutions). The kit provides for a more immersive experience. With the kit and a Linux or Android client app, you can control a Raspberry Pi equipped with colored LEDs and capacitive touch buttons on an add-on board.