From cec955014eca2f6ef60d986933c1616a130b7ffb Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Fri, 6 Mar 2020 16:25:52 -0700 Subject: [PATCH 1/8] Fixing examples Fixed bad instructions for Raspberry Pi and added an example for the GTK GUI example --- gsg-gtk.md | 424 +++++++++++++++++++++++++++++++++++++++++++++++++++++ gsg-kit.md | 111 ++++++-------- gsg-sw.md | 41 +++--- index.md | 6 +- 4 files changed, 500 insertions(+), 82 deletions(-) create mode 100644 gsg-gtk.md diff --git a/gsg-gtk.md b/gsg-gtk.md new file mode 100644 index 0000000..547a6c7 --- /dev/null +++ b/gsg-gtk.md @@ -0,0 +1,424 @@ +![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) + +# Getting Started with IoTivity (Raspberry Pi Kit) + +## Introduction + +This Getting Started guide will show you how to quickly download, build, and run IoTivity apps, featuring two-way communication between a Linux or Android device and a Raspberry Pi with an add-in Pimoroni board. This simple platform enables you to quickly prototype the capabilities of your planned smart device: + +- The *server*, a command-line app, runs on a smart home device, such as a smart switch or smart thermostat, represented by the Raspberry Pi board. + +- The *client*, a GUI app, controls the smart device from a Linux computer or Android tablet. + +The two apps talk to each other over Wi-Fi, using the OCF (Open Connectivity Foundation) protocol. + + +![OCF protocol](/Images/communication-over-ocf-protocol.png) + + +## Requirements + +To carry out this tutorial, you will need the following: + +- Raspberry Pi board with microSD card with Raspbian OS + +- Pimoroni Explorer HAT board + +- Optional: HDMI monitor and cable for the Pi + +- Optional: USB mouse for the Pi + +- Ethernet or Wi-Fi connection between a DHCP-enabled network and the Pi + +- Linux computer or Android tablet on the same network as the Pi + + +The first two listed items are sold together as a kit [here](https://openconnectivity.org/developer/developer-kit) (scroll down, below "Development Resources and Solutions"). + + +## Set up the Raspberry Pi + + +1. *Before* connecting power, attach the Explorer HAT board to the GPIO header on the Raspberry Pi. Be careful not to bend the pins, as the connector fits very tightly. (At this point, you don’t need the blue breadboard, which may be attached later.) + + + ![OCF protocol](/Images/attach-HAT-plus-blue-board.png) + + +2. Insert the micro SD card with an updated version of Raspian already installed into its slot, located under the Pi board. + + +3. Connect an Ethernet cable between the Pi board and network or connect via Wi-Fi. This will be easier if you have a monitor and keyboard to check the IP address of the Raspberry Pi. + + +4. Attach the power cable to the Pi board, and plug it in. + + + The board will boot. + + +## Connect to the Raspberry Pi + + +The steps in this section use SSH. As an alternative, attach a monitor and USB keyboard to the Raspberry Pi. + + +1. Open a terminal on your development PC. + + +2. Learn the Raspberry Pi board’s IP address by giving this command from the command line of your Linux PC, then pressing ctrl-C. Use the host name of the Pi, which is raspberrypi unless you have changed it: + + + ``` + ping raspberrypi.local + ``` + + + ![ping Pi](/Images/ping-pi-local.png) + + + In the screen above, the IP address is 192.168.0.30. + + + Sometimes the ping command doesn't reach raspberrypi.local due to DNS issues. An alternative is to connect a keyboard and monitor to the Pi and run the ifconfig command in the terminal. + + +4. Connect to the Pi via SSH, using either of these commands: + + + For Linux or macOS, use either of these commands: + + + ``` + ssh pi@raspberrypi.local #replace with current hostname if changed, OR... + ``` + + ​ OR + + + ``` + ssh pi@ipaddress #use IP address from previous step + ``` + + + +5. Supply the password when prompted. Default login: + + + *username* **pi** + *password* **raspberry** + + + ![ssh prompt](/Images/ssh-prompt.png) + + +You’re now ready to install IoTivity code and samples. + + +## Install IoTivity and Pi Samples + +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: + + + ``` + 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. + + +2. 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, which takes several minutes to run. Answer “y” if prompted: + + + ``` + curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash + ``` + + +5. Build the sample project in a new directory: + + + ``` + 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 + ``` + + + 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: + + + + ``` + sudo raspi-config #enter the Pi account password, if prompted. + ``` + + +2. In the Raspberry Pi Software Configuration Tool (raspi-config) menu, choose: + + * **Localization Options** or **Internationalization Options** + * **Change Keyboard Layout** + + + 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. + + + Then reboot with sudo: + + ``` + sudo reboot + ``` + +3. On the Pi, create a project directory: + + ``` + cd ~ + mkdir workspace + cd workspace + ``` + +4. Create the IoTivity project: + + ``` + create_project.sh myexample + cd myexample + ``` + +5. 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. + + +## Build and Run the Server App + + +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 + ``` + + + 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). + +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 + ``` + + +Leave this 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 + +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. In the Generic Client tab, toggle the Value switch on and off. + + + +6. **[Todo OCF: We could not successfully execute the remaining steps.]** Quit the client app and then press Ctrl-C in the server terminal to exit the process. + + +7. 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. Find the /LED1, /LED2, and /LED3 sections and in each, click the switch button on the left. **[Todo OCF: insert screenshot /LED section with callout to value button]** The colored LEDs on the Explorer HAT board turn on or off, controlled by the client app over the OCF protocol. Notice that the console output in the server terminal on the Pi responds to your actions in the client. If you do not have the Explorer HAT board, the green light on the Pi will flash. + + +10. Now “observe” (monitor) the touch buttons on the Explorer HAT board in the OTGC app by clicking the switch buttons on the right of the /touch1, /touch2, and /touch3 sections. Physically touch the buttons on the board numbered 1, 2, and 3. **[Todo OCF: insert screenshot]** Notice that the output in the OTGC app detects the touches. (This step does not apply if you do not have the Explorer HAT board.) + + +11. Press Ctrl-C in the server terminal on the Pi to exit the server app. + + +## Customize the Code + + + +*** + +**[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.] + + +*** + + + + + +IoTivity provides a tool for automatically generating server code as a significant head start for your software development. The code generation tool works from a JSON file created by you that describes the capabilities of your device. The server code you compiled and ran in this tutorial began from example.json file, found in the ~/iot-lite/ directory on your development PC. + + + + + +The steps below will show you how to make a simple change to the JSON file, recompile, and run the server and client. You can then see how the changes you made to the server’s capabilities in the JSON file are reflected in the client app. + + + + + +1. On your development PC, back up the example.json file: + + + + + + ``` + cd ~/iot-lite/ + cp example.json example.json.bak + ``` + + + + + +2. Open the example.json file in your preferred editor. + + +3. **[Todo OCF: Insert here the editing changes that user will make]** + + +4. While still in the ~/iot-lite/ directory, generate the server code, build, and run: + + + ``` + ./gen.sh + ./build.sh + ./run.sh + ``` + + +5. Run the client app: + + + ``` + /usr/bin/otgc.sh + ``` + + +6. As before, select the discovered device. Notice the changed capabilities. + + +*** +**[Todo OCF: Based on the detail in step 3 above, insert screenshot of relevant section in OTGC with callout to changes]** +*** + + +## 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..4cc577e 100755 --- a/gsg-kit.md +++ b/gsg-kit.md @@ -113,6 +113,29 @@ 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 + + +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: + + ``` + sudo raspi-config #enter the Pi account password, if prompted. + ``` + +2. In the Raspberry Pi Software Configuration Tool (raspi-config) menu, choose: + + * **Localization Options** or **Internationalization Options** + * **Change Keyboard Layout** + + + 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. + + + Then reboot with sudo: + + ``` + sudo reboot + ``` You’re now ready to install IoTivity code and samples. @@ -144,59 +167,19 @@ You’re now ready to install IoTivity code and samples. ``` - curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash - ``` - - -5. Build the sample project in a new directory: - - - ``` - 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 - ``` - - - 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: - - - - ``` - 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 @@ -230,26 +213,26 @@ The sample project now has Explorer HAT drivers installed and is ready for code ``` cd ~/iot-lite/ #or path where you installed IoTivity - ./gen.sh + 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. From 47221e69ef988d74d896350b0350331688f60bf4 Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 11:31:29 -0600 Subject: [PATCH 2/8] Fixed text --- gsg-gtk.md | 277 +++++++---------------------------------------------- gsg-kit.md | 4 +- 2 files changed, 35 insertions(+), 246 deletions(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index 547a6c7..568f690 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -2,17 +2,17 @@ [**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) -# Getting Started with IoTivity (Raspberry Pi Kit) +# Getting Started with IoTivity (Linux graphical user interface (GUI) using GTK) ## Introduction -This Getting Started guide will show you how to quickly download, build, and run IoTivity apps, featuring two-way communication between a Linux or Android device and a Raspberry Pi with an add-in Pimoroni board. This simple platform enables you to quickly prototype the capabilities of your planned smart device: +This Getting Started guide will show you how to quickly download, build, and run IoTivity apps, featuring two-way communication between a Linux or Android device and a Linux dimmable light emulator server with a GUI and controls on the server. This simple platform enables you to quickly prototype the capabilities of your planned smart device: -- The *server*, a command-line app, runs on a smart home device, such as a smart switch or smart thermostat, represented by the Raspberry Pi board. +- The *server*, a command-line app, runs here as a GUI emulator of a smart home device, such as a smart switch or smart thermostat. In this case, this is represented by emulator code on the Linux machine of a dimmable light. - The *client*, a GUI app, controls the smart device from a Linux computer or Android tablet. -The two apps talk to each other over Wi-Fi, using the OCF (Open Connectivity Foundation) protocol. +The two apps talk to each other via a loopback connection on the same machine, using the OCF (Open Connectivity Foundation) protocol. This also works for the code running on a different Linux machine if that machine is on the same local area network. ![OCF protocol](/Images/communication-over-ocf-protocol.png) @@ -22,104 +22,12 @@ The two apps talk to each other over Wi-Fi, using the OCF (Open Connectivity Fou To carry out this tutorial, you will need the following: -- Raspberry Pi board with microSD card with Raspbian OS +- Linux computer -- Pimoroni Explorer HAT board -- Optional: HDMI monitor and cable for the Pi +## Install IoTivity and Emulator Sample -- Optional: USB mouse for the Pi - -- Ethernet or Wi-Fi connection between a DHCP-enabled network and the Pi - -- Linux computer or Android tablet on the same network as the Pi - - -The first two listed items are sold together as a kit [here](https://openconnectivity.org/developer/developer-kit) (scroll down, below "Development Resources and Solutions"). - - -## Set up the Raspberry Pi - - -1. *Before* connecting power, attach the Explorer HAT board to the GPIO header on the Raspberry Pi. Be careful not to bend the pins, as the connector fits very tightly. (At this point, you don’t need the blue breadboard, which may be attached later.) - - - ![OCF protocol](/Images/attach-HAT-plus-blue-board.png) - - -2. Insert the micro SD card with an updated version of Raspian already installed into its slot, located under the Pi board. - - -3. Connect an Ethernet cable between the Pi board and network or connect via Wi-Fi. This will be easier if you have a monitor and keyboard to check the IP address of the Raspberry Pi. - - -4. Attach the power cable to the Pi board, and plug it in. - - - The board will boot. - - -## Connect to the Raspberry Pi - - -The steps in this section use SSH. As an alternative, attach a monitor and USB keyboard to the Raspberry Pi. - - -1. Open a terminal on your development PC. - - -2. Learn the Raspberry Pi board’s IP address by giving this command from the command line of your Linux PC, then pressing ctrl-C. Use the host name of the Pi, which is raspberrypi unless you have changed it: - - - ``` - ping raspberrypi.local - ``` - - - ![ping Pi](/Images/ping-pi-local.png) - - - In the screen above, the IP address is 192.168.0.30. - - - Sometimes the ping command doesn't reach raspberrypi.local due to DNS issues. An alternative is to connect a keyboard and monitor to the Pi and run the ifconfig command in the terminal. - - -4. Connect to the Pi via SSH, using either of these commands: - - - For Linux or macOS, use either of these commands: - - - ``` - ssh pi@raspberrypi.local #replace with current hostname if changed, OR... - ``` - - ​ OR - - - ``` - ssh pi@ipaddress #use IP address from previous step - ``` - - - -5. Supply the password when prompted. Default login: - - - *username* **pi** - *password* **raspberry** - - - ![ssh prompt](/Images/ssh-prompt.png) - - -You’re now ready to install IoTivity code and samples. - - -## Install IoTivity and Pi Samples - -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: +1. Continuing on your development PC, from the terminal prompt, go to the home directory and install the IoTivity-lite development system, which takes a few minutes to complete: ``` @@ -147,56 +55,13 @@ You’re now ready to install IoTivity code and samples. curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash ``` + You may need to reboot the Raspberry Pi at this point to ensure that your environment variables are set. -5. Build the sample project in a new directory: - - - ``` - 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 - ``` - - - 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: - - - - ``` - sudo raspi-config #enter the Pi account password, if prompted. - ``` - - -2. In the Raspberry Pi Software Configuration Tool (raspi-config) menu, choose: - - * **Localization Options** or **Internationalization Options** - * **Change Keyboard Layout** - - - 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. + ``` + sudo reboot -h now + ``` - - Then reboot with sudo: - - ``` - sudo reboot - ``` - -3. On the Pi, create a project directory: +5. Create a project directory: ``` cd ~ @@ -204,33 +69,31 @@ 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 - ``` + ``` + create_project.sh myexample + cd myexample + ``` 5. Copy the sample project to the current directory and set it up: ``` - cp ~/Sample-Raspberry-Pi-Code/IoTivity-lite/explorer-hat-pro/setup.sh ./ + cp ~/Emulator-Code/IoTivity-lite/emulator/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. +The sample project now has all dependencies installed and is ready for code generation and building. ## Build and Run the Server App -1. On the Pi, generate code for the server app by running these commands: +1. 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 ``` @@ -240,7 +103,7 @@ The sample project now has Explorer HAT drivers installed and is ready for code ``` - ./build.sh + build.sh ``` @@ -248,16 +111,19 @@ The sample project now has Explorer HAT drivers installed and is ready for code ``` - ./reset.sh - ./run.sh + 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. -Leave this 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.) -## Build and Run the Client App +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: @@ -329,90 +195,13 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client 8. Once the + icon has changed to a gear, click the gear icon. **[Todo OCF: insert screenshot with callout to gear]** -9. Find the /LED1, /LED2, and /LED3 sections and in each, click the switch button on the left. **[Todo OCF: insert screenshot /LED section with callout to value button]** The colored LEDs on the Explorer HAT board turn on or off, controlled by the client app over the OCF protocol. Notice that the console output in the server terminal on the Pi responds to your actions in the client. If you do not have the Explorer HAT board, the green light on the Pi will flash. - - -10. Now “observe” (monitor) the touch buttons on the Explorer HAT board in the OTGC app by clicking the switch buttons on the right of the /touch1, /touch2, and /touch3 sections. Physically touch the buttons on the board numbered 1, 2, and 3. **[Todo OCF: insert screenshot]** Notice that the output in the OTGC app detects the touches. (This step does not apply if you do not have the Explorer HAT board.) - - -11. Press Ctrl-C in the server terminal on the Pi to exit the server app. - - -## Customize the Code - - - -*** - -**[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.] - - -*** - - - - - -IoTivity provides a tool for automatically generating server code as a significant head start for your software development. The code generation tool works from a JSON file created by you that describes the capabilities of your device. The server code you compiled and ran in this tutorial began from example.json file, found in the ~/iot-lite/ directory on your development PC. - - - - - -The steps below will show you how to make a simple change to the JSON file, recompile, and run the server and client. You can then see how the changes you made to the server’s capabilities in the JSON file are reflected in the client app. - - - - - -1. On your development PC, back up the example.json file: - - - - - - ``` - cd ~/iot-lite/ - cp example.json example.json.bak - ``` - - - - - -2. Open the example.json file in your preferred editor. - - -3. **[Todo OCF: Insert here the editing changes that user will make]** - - -4. While still in the ~/iot-lite/ directory, generate the server code, build, and run: - - - ``` - ./gen.sh - ./build.sh - ./run.sh - ``` - - -5. Run the client app: - - - ``` - /usr/bin/otgc.sh - ``` +9. Find the /light sections and click the switch 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. Notice that the console output in the server terminal on the Pi responds to your actions in the client. -6. As before, select the discovered device. Notice the changed capabilities. +10. Now “observe” (monitor) the touch buttons on the emulator window in the OTGC app by turning on the "observe" button on the switch and dimmer sections of OTGC, then clicking the switch button or dimming slider on emulator application. **[Todo OCF: insert screenshot]** Notice that the output in the OTGC app detects the changes in the emulator application. (This step does not apply if you do not have the Explorer HAT board.) -*** -**[Todo OCF: Based on the detail in step 3 above, insert screenshot of relevant section in OTGC with callout to changes]** -*** +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 diff --git a/gsg-kit.md b/gsg-kit.md index 4cc577e..e02adba 100755 --- a/gsg-kit.md +++ b/gsg-kit.md @@ -163,7 +163,7 @@ You’re now ready to install IoTivity code and samples. Rerun this script if an error occurs. -4. Install the repository containing emulator sample code, which takes several minutes to run. Answer “y” if prompted: +4. Install the repository containing the Raspberry Pi sample code, which takes several minutes to run. Answer “y” if prompted: ``` @@ -212,7 +212,7 @@ The sample project now has Explorer HAT (or no HAT) drivers installed and is rea 1. On the Pi, generate code for the server app by running these commands: ``` - cd ~/iot-lite/ #or path where you installed IoTivity + cd ~/workspace/myexample (if not already there) gen.sh ``` From eb5dbc8b10f0d69d59ceafcd9d01d91ab1f332aa Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 12:18:41 -0600 Subject: [PATCH 3/8] test --- gsg-gtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index 568f690..b78a054 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -2,7 +2,7 @@ [**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) -# Getting Started with IoTivity (Linux graphical user interface (GUI) using GTK) +# Getting Started with IoTivity (the Linux graphical user interface (GUI) using GTK) ## Introduction From d5346420c0159fe7181ea87ee75c990f942e7cdc Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 12:24:01 -0600 Subject: [PATCH 4/8] Another test --- gsg-gtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index b78a054..568f690 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -2,7 +2,7 @@ [**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) -# Getting Started with IoTivity (the Linux graphical user interface (GUI) using GTK) +# Getting Started with IoTivity (Linux graphical user interface (GUI) using GTK) ## Introduction From c70ce4758bf5bd4f12651a3ba6175a3e22a23613 Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 13:17:28 -0600 Subject: [PATCH 5/8] Fixed graphics --- gsg-gtk.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index 568f690..49e43bb 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -2,33 +2,28 @@ [**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) -# Getting Started with IoTivity (Linux graphical user interface (GUI) using GTK) +This guide will show you how to download, build, and run two simulated devices on the same Linux PC: -## Introduction +- 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. -This Getting Started guide will show you how to quickly download, build, and run IoTivity apps, featuring two-way communication between a Linux or Android device and a Linux dimmable light emulator server with a GUI and controls on the server. This simple platform enables you to quickly prototype the capabilities of your planned smart device: +The two apps talk to each other over a loopback connection, using the OCF protocol. -- The *server*, a command-line app, runs here as a GUI emulator of a smart home device, such as a smart switch or smart thermostat. In this case, this is represented by emulator code on the Linux machine of a dimmable light. - -- The *client*, a GUI app, controls the smart device from a Linux computer or Android tablet. - -The two apps talk to each other via a loopback connection on the same machine, using the OCF (Open Connectivity Foundation) protocol. This also works for the code running on a different Linux machine if that machine is on the same local area network. - - -![OCF protocol](/Images/communication-over-ocf-protocol.png) +![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: -- Linux computer - +- A Debian-based Linux PC (e.g., Ubuntu), with an internet connection. ## Install IoTivity and Emulator Sample -1. Continuing on your development PC, from the terminal prompt, go to the home directory and install the IoTivity-lite development system, which takes a few minutes to complete: +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 ~ @@ -38,7 +33,7 @@ To carry out this tutorial, you will need the following: Alternatively, you can download the install.sh script, review and run it from anywhere. -2. Install the project scripts: +3. Install the project scripts: ``` @@ -55,9 +50,13 @@ To carry out this tutorial, you will need the following: curl https://openconnectivity.github.io/Emulator-Code/emulator/install.sh | bash ``` - You may need to reboot the Raspberry Pi at this point to ensure that your environment variables are set. + 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 ``` From abae6bcbfb9b6ba8f034f36aacc5998aa17c62ef Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 13:28:07 -0600 Subject: [PATCH 6/8] General updates to text --- gsg-gtk.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index 49e43bb..ab222a4 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -43,7 +43,7 @@ To carry out this tutorial, you will need the following: Rerun this script if an error occurs. -4. Install the repository containing emulator sample code, which takes several minutes to run. Answer “y” if prompted: +4. Install the repository containing emulator sample code. Answer “y” if prompted: ``` @@ -185,7 +185,7 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client -6. **[Todo OCF: We could not successfully execute the remaining steps.]** Quit the client app and then press Ctrl-C in the server terminal to exit the process. +6. Quit the client app and then press Ctrl-C in the server terminal to exit the process. 7. 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. @@ -194,10 +194,10 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client 8. Once the + icon has changed to a gear, click the gear icon. **[Todo OCF: insert screenshot with callout to gear]** -9. Find the /light sections and click the switch 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. Notice that the console output in the server terminal on the Pi responds to your actions in the client. +9. Find the /light 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. Notice that the console output in the server terminal on the Pi 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 switch and dimmer sections of OTGC, then clicking the switch button or dimming slider on emulator application. **[Todo OCF: insert screenshot]** Notice that the output in the OTGC app detects the changes in the emulator application. (This step does not apply if you do not have the Explorer HAT board.) +10. Now “observe” (monitor) the touch buttons on the emulator window in the OTGC app by turning on the "observe" button on the /switch 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. (This step does not apply if you do not have the Explorer HAT board.) 11. Press Ctrl-C in the server terminal or click the "X" in the emulator window to exit the server app. From 8442d1fca0b55ca5c6e1e61f76d05256eb60323c Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Mon, 9 Mar 2020 13:33:50 -0600 Subject: [PATCH 7/8] added android OTGC link --- gsg-gtk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index ab222a4..e46bac8 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -122,7 +122,7 @@ Leave the terminal window open. The server app is now waiting for commands from ## 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). +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 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: From 4768a6d17ea4488987cb75ff3259a7f36ee18d84 Mon Sep 17 00:00:00 2001 From: Clarke Stevens Date: Tue, 10 Mar 2020 09:33:14 -0600 Subject: [PATCH 8/8] More edits --- gsg-gtk.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/gsg-gtk.md b/gsg-gtk.md index e46bac8..428e3a1 100644 --- a/gsg-gtk.md +++ b/gsg-gtk.md @@ -96,7 +96,7 @@ The sample project now has all dependencies installed and is ready for code gene ``` - 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 dimmable light Emulator app). 2. Build the server app with this command: @@ -122,7 +122,7 @@ Leave the terminal window open. The server app is now waiting for commands from ## 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 Raspberry Pi server (make sure you're on the same LAN). +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: @@ -181,23 +181,19 @@ The sample client application is called OTGC (Onboarding Tool and Generic Client - Change the device name, if you wish. Click OK to close the dialog box. - - Click to reselect the device in the left-hand pane. In the Generic Client tab, toggle the Value switch on and off. + - Click to reselect the device in the left-hand pane. - -6. Quit the client app and then press Ctrl-C in the server terminal to exit the process. - - -7. 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. +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. Find the /light 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. Notice that the console output in the server terminal on the Pi responds to your actions in the client. +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 /switch 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. (This step does not apply if you do not have the Explorer HAT board.) +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.