Commit abd622fc authored by George Nash's avatar George Nash Committed by Rick Bell

Update the SWIG README.md files

- minor update to the description of what SWIG is
- removed C++ as a requirement since we now only require C
- Indicated SWIG version 3.0 was used for developement not the
  newer version 4.0
- Removed Oracle Java from the list of version of Java code was
  tested against. Indicated this was due to changes in the way
  Oracle licenses Java.
- Added link to download AdoptOpenJDK since this is the version
  Java currently found on my windows computer.
- Minor rewording of install instructions
- Removed request for feedback in the section talking about
  Visual Studio.
- Updated the onboarding and provisioning section. The
  Onboarding tool has change a lot since the original
  section was writen. I removed most of the example output.
  It now just instructs the developers on the expected input not
  output.
- Added a small block talking about the Android version of the
  onboarding tool.
- removed the instructions to copy the iotivity-lite-jni library
  to the iotiviy-lite-java project. This is now done
  automatically by build scripts on the 3 supported operating
  systems
- Change the directory layout to use ascii characters instead
  of UTF-8 characters they were causing layout issues on
  windows which was expecting Cp1252.
- Removed the indication that the bindings are still in early
  stage and subject to change. Although this is still a true
  statment the change has slowed down and we want to appear
  as stable as possible.
- Same changes made to the onboarding and provisioning section
  of the Android README.md as were made to the swig README.md
Change-Id: I6b192051c766ba5b52667c8eee6fe16e7c7fe42a
Signed-off-by: George Nash's avatarGeorge Nash <george.nash@intel.com>
parent 4de25735
......@@ -151,20 +151,18 @@ Onboarding and Provisioning
=================================================
### Runing the onboarding tool
At this time there are two versions of the onboarding tool. The C version and the Java version.
The versions are identical. The exception being that the C version is currently built only for
Linux. While the Java version is available for both windows and Linux. It does not matter which
version of the onboarding tool.
At this time there are three versions of the onboarding tool. The command line C version, the
command line Java version, and the GUI Android version. Both command line versions are identical.
It does not matter which version of the onboarding tool is used.
The C version of the onboarding tool can be found in `<iotivity-lite>/port/linux` see Linux build
instructions.
A Java version of the onboarding-tool that will run on Windows or Linux can be found
A sample server and client can be found in `<iotivity-lite>/swig/apps/java_onboarding_tool`
A Java version of the onboarding-tool can be found in `<iotivity-lite>/swig/apps/java_onboarding_tool`
Assuming you have already followed the `Building for Linux` or `Building for Windows` build
instructions the following commands can be used to build and run the onboarding tool.
instructions the following commands can be used to build and run the Java version of the onboarding
tool.
Linux:
......@@ -176,6 +174,11 @@ Windows
sh build-onboarding-tool-lite.sh
run-onboarding-tool-lite.cmd
The Android version of the onboarding tool can be found in
`<iotivity-lite>/swig/apps/oc/android_on_boarding_tool`
It is built and installed using the same instructions as other Android samples documented above.
### Simple Step-by-Step guide for onboarding and provisioning
This guide assumes you are starting one discoverable device at a time. Multiple devices can be
......@@ -185,48 +188,23 @@ figure out which UUID belongs to which device.
Once you have successfully onboarded the samples the first time using the following step-by-step
options feel free to RESET the devices and play around with different provisioning options.
### (Step 1) Onboard and Provision the Server
- start the server sample
- start onboarding tool it will print the following menu:
```
################################################
OCF 1.3 Onboarding Tool
################################################
[0] Display this menu
-----------------------------------------------
[1] Discover un-owned devices
[2] Discover owned devices
-----------------------------------------------
[3] Take ownership of device (Just-works)
[4] Provision pair-wise credentials
[5] Provision ACE2
-----------------------------------------------
[6] RESET device
-----------------------------------------------
[9] Exit
################################################
Select option:
```
The below steps use the command line version of the onboarding tool. The steps for the Android
onboarding tool is very similar but is not described here.
- Type `1` **Enter** to _Discover un-owned devices_ this should display a something similar to
this
### (Step 1) Onboard and Provision the Server
Discovered unowned device: c3e5c231-9f95-4859-6d11-87f40b1977d5 at:
[fe80:0000:0000:0000:05a8:81bd:23cf:3882]:59584
[fe80:0000:0000:0000:05a8:81bd:23cf:3882]:59585
There are multiple methods to onboard and provision server and client samples. Below is given one
of the many possible ways the this could be done.
- Type `3` **Enter** to _Take ownership of device_
- start the server sample
- start onboarding tool it will print a menu with many option
- Type `1` **Enter** to _Discover un-owned devices_
- Type `8` **Enter** to _Take ownership of device_
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list. The following should be displayed
Successfully issued request to perform ownership transfer
- Type `2` **Enter** to _Discover owned devices_ the device you just took ownership of should be
device from the list.
- Type `4` **Enter** to _Discover owned devices_ the device you just took ownership of should be
listed.
- Type `5` **Enter** to _Provision ACE2_. There are many ways to properly provision the device.
- Type `13` **Enter** to _Provision ACE2_. There are many ways to properly provision the device.
This will give instruction for using wildcard provisioning.
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list.
......@@ -241,61 +219,22 @@ options feel free to RESET the devices and play around with different provisioni
**Enter** for DELETE, and `1` **Enter** for NOTIFY.
- `Successfully issued request to provision ACE` should be printed on the screen upon success
Example output from following the above listed commands:
Provision ACL2
My Devices:
[0]: 33cd6782-00f3-49db-624e-fda26e945c8d
Select device for provisioning: 0
Subjects:
[0]: anon-clear
[1]: auth-crypt
[2]: 33cd6782-00f3-49db-624e-fda26e945c8d
Select subject: 1
Enter number of resources in this ACE: 1
Resource properties
Have resource href? [0-No, 1-Yes]: 0
Set wildcard resource? [0-No, 1-Yes]: 1
[1]: All resources
[2]: All discoverable resources
[3]: All non-discoverable resources
Select wildcard resource: 2
Enter number of resource types [0-None]: 0
Enter number of interfaces [0-None]0
Set ACE2 permissions
CREATE [0-No, 1-Yes]: 0
RETRIEVE [0-No, 1-Yes]: 1
UPDATE [0-No, 1-Yes]: 1
DELETE [0-No, 1-Yes]: 0
NOTIFY [0-No, 1-Yes]: 1
Successfully issued request to provision ACE
### (Step 2) Onboard the client
- start the client sample
- Type `1` **Enter** to _Discover un-owned devices_
- Type `3` **Enter** to _Take ownership of device_
- Type `8` **Enter** to _Take ownership of device_
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list.
- Type `2` **Enter** to _Discover owned devices_ the server and client should be listed
### (Step 3) Pair Server and Client
- Type `4` **Enter** to _Provision pair-wise credentials_
- Type `12` **Enter** to _Provision pair-wise credentials_
- Type `0` **Enter** `1` **Enter** to pair the client and server. If you have multiple owned
devices you will have to select the correct devices from the list.
### (Step 4) Restart and Test
The samples should be onboarded and provisioned. Restart the server and client they should discover
each other and run without difficulty.
The samples should be onboarded and provisioned. Restart the server and then the client they should
discover each other and run without difficulty.
Building Custom Android Applications
=================================================
......
......@@ -7,7 +7,7 @@ A tool called SWIG is used to generate Java language bindings for IoTivity-Lite.
interface compiler that connects programs written in C and C++ with other languages such as Java.
SWIG is not a stubs generator. It produces code that can be compiled and used. The output is
generated by a tool. For this reason there is no encapsulation of the code to make it
generated by a tool. For this reason there is little or no encapsulation of the code to make it
appear more like what most Java developers would expect. The output with very few
exceptions are just a collection of classes filled with static methods. This has both the
advantage and disadvantage that the way the code is used in Java is similar to the way it is used
......@@ -25,7 +25,7 @@ To use this code you will need the following:
- A local copy of IoTivity-Lite
- SWIG installed on your local system
- Java Development kit.
- C and C++ build tool for your desired system
- C build tool for your desired system
### Get git
It can be installed on Ubuntu Linux using the following command.
......@@ -51,7 +51,7 @@ IoTivity you will need to have a [Linux Foundation ID](https://identity.linuxfou
The Linux Foundation ID can then be used to log into the Gerrit server for IoTivity-Lite.
[gerrit.iotivity.org](https://gerrit.iotivity.org/gerrit/#/admin/projects/iotivity-lite)
Follow the instruction [here](https://wiki.iotivity.org/how_to_use_gerrit) to gain push access
Follow the instructions [here](https://wiki.iotivity.org/how_to_use_gerrit) to gain push access
to the project.
### Get SWIG
......@@ -61,13 +61,19 @@ SWIG can be installed on Ubuntu Linux using the following command.
sudo apt-get install swig
The code was developed using SWIG version 3.0. It has not been tested against SWIG version 4.0 that
was released when the swig branch was being developed. Developers are welcome to use SWIG v4.0 and
share their experiences.
### Get Java Development Kit
The SWIG output should work with Java 6 and newer. The Output has been tested against Oracle
Java 8 and OpenJDK 1.8.
The SWIG output should work with Java 6 and newer. The Output has been tested against OpenJDK 1.8.
Due to licensing changes the output is no longer tested against Oracle Java.
Oracle Java 8 JDK can be
[downloaded here](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
AdoptOpenJDK can be [downloaded here](https://adoptopenjdk.net/installation.html)
On Ubuntu Linux OpenJDK can be downloaded using the following command.
#To find out the avalible versions of OpenJDK
......@@ -79,7 +85,7 @@ On Ubuntu Linux OpenJDK can be downloaded using the following command.
sudo apt-get install java-common
update-java-alternatives
Install OpenJDK on Fedora Linux
On Fedora Linux Install OpenJDK can be done using the following command
sudo dnf install java-1.8.0-openjdk.x86_64
# or use dnf install <openjdk-package-name>
......@@ -87,8 +93,8 @@ Install OpenJDK on Fedora Linux
# the active version
sudo alternatives --config java
If you wish to use a different version of OpenJDK you can use the following command so see which
versions are avalible
To find different version of OpenJDK use the following command so see which
versions are available
apt-cache search openjdk
......@@ -147,8 +153,7 @@ For Ubuntu Linux GCC compiler was used
#### Windows
For development on Windows Visual Studio 2015 was used. The Visual Studio solution files have
been tested in newer version of Visual Studio and have been found to work. Visual studio IDE
Community edition and Visual Studio Code should work but have not personally been tested. If you
find that the compiler does not work please give us feed back.
Community edition and Visual Studio Code should work but have not personally been tested.
Download Visual Studio [here](https://visualstudio.microsoft.com/).
......@@ -189,7 +194,7 @@ SWIG
swig -version
example of expected output (newest version recommended)
example of expected output (version 3.0 currently recommended)
SWIG Version 3.0.12
Compiled with g++ [x86_64-redhat-linux-gnu]
......@@ -350,20 +355,18 @@ Onboarding and Provisioning
=================================================
### Runing the onboarding tool
At this time there are two versions of the onboarding tool. The C version and the Java version.
The versions are identical. The exception being that the C version is currently built only for
Linux. While the Java version is available for both windows and Linux. It does not matter which
version of the onboarding tool.
At this time there are three versions of the onboarding tool. The command line C version, the
command line Java version, and the GUI Android version. Both command line versions are identical.
It does not matter which version of the onboarding tool is used.
The C version of the onboarding tool can be found in `<iotivity-lite>/port/linux` see Linux build
instructions.
A Java version of the onboarding-tool that will run on Windows or Linux can be found
A sample server and client can be found in `<iotivity-lite>/swig/apps/java_onboarding_tool`
A Java version of the onboarding-tool can be found in `<iotivity-lite>/swig/apps/java_onboarding_tool`
Assuming you have already followed the `Building for Linux` or `Building for Windows` build
instructions the following commands can be used to build and run the onboarding tool.
instructions the following commands can be used to build and run the Java version of the onboarding
tool.
Linux:
......@@ -375,6 +378,11 @@ Windows
sh build-onboarding-tool-lite.sh
run-onboarding-tool-lite.cmd
The Android version of the onboarding tool can be found in
`<iotivity-lite>/swig/apps/oc/android_on_boarding_tool`
It is built and installed using the same instructions as other Android samples documented above.
### Simple Step-by-Step guide for onboarding and provisioning
This guide assumes you are starting one discoverable device at a time. Multiple devices can be
......@@ -384,48 +392,23 @@ figure out which UUID belongs to which device.
Once you have successfully onboarded the samples the first time using the following step-by-step
options feel free to RESET the devices and play around with different provisioning options.
### (Step 1) Onboard and Provision the Server
- start the server sample
- start onboarding tool it will print the following menu:
```
################################################
OCF 1.3 Onboarding Tool
################################################
[0] Display this menu
-----------------------------------------------
[1] Discover un-owned devices
[2] Discover owned devices
-----------------------------------------------
[3] Take ownership of device (Just-works)
[4] Provision pair-wise credentials
[5] Provision ACE2
-----------------------------------------------
[6] RESET device
-----------------------------------------------
[9] Exit
################################################
Select option:
```
The below steps use the command line version of the onboarding tool. The steps for the Android
onboarding tool is very similar but is not described here.
- Type `1` **Enter** to _Discover un-owned devices_ this should display a something similar to
this
### (Step 1) Onboard and Provision the Server
Discovered unowned device: c3e5c231-9f95-4859-6d11-87f40b1977d5 at:
[fe80:0000:0000:0000:05a8:81bd:23cf:3882]:59584
[fe80:0000:0000:0000:05a8:81bd:23cf:3882]:59585
There are multiple methods to onboard and provision server and client samples. Below is given one
of the many possible ways the this could be done.
- Type `3` **Enter** to _Take ownership of device_
- start the server sample
- start onboarding tool it will print a menu with many option
- Type `1` **Enter** to _Discover un-owned devices_
- Type `8` **Enter** to _Take ownership of device_
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list. The following should be displayed
Successfully issued request to perform ownership transfer
- Type `2` **Enter** to _Discover owned devices_ the device you just took ownership of should be
device from the list.
- Type `4` **Enter** to _Discover owned devices_ the device you just took ownership of should be
listed.
- Type `5` **Enter** to _Provision ACE2_. There are many ways to properly provision the device.
- Type `13` **Enter** to _Provision ACE2_. There are many ways to properly provision the device.
This will give instruction for using wildcard provisioning.
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list.
......@@ -440,61 +423,22 @@ options feel free to RESET the devices and play around with different provisioni
**Enter** for DELETE, and `1` **Enter** for NOTIFY.
- `Successfully issued request to provision ACE` should be printed on the screen upon success
Example output from following the above listed commands:
Provision ACL2
My Devices:
[0]: 33cd6782-00f3-49db-624e-fda26e945c8d
Select device for provisioning: 0
Subjects:
[0]: anon-clear
[1]: auth-crypt
[2]: 33cd6782-00f3-49db-624e-fda26e945c8d
Select subject: 1
Enter number of resources in this ACE: 1
Resource properties
Have resource href? [0-No, 1-Yes]: 0
Set wildcard resource? [0-No, 1-Yes]: 1
[1]: All resources
[2]: All discoverable resources
[3]: All non-discoverable resources
Select wildcard resource: 2
Enter number of resource types [0-None]: 0
Enter number of interfaces [0-None]0
Set ACE2 permissions
CREATE [0-No, 1-Yes]: 0
RETRIEVE [0-No, 1-Yes]: 1
UPDATE [0-No, 1-Yes]: 1
DELETE [0-No, 1-Yes]: 0
NOTIFY [0-No, 1-Yes]: 1
Successfully issued request to provision ACE
### (Step 2) Onboard the client
- start the client sample
- Type `1` **Enter** to _Discover un-owned devices_
- Type `3` **Enter** to _Take ownership of device_
- Type `8` **Enter** to _Take ownership of device_
- Type `0` **Enter**. If you have multiple unowned devices you will have to select the correct
device from the list.
- Type `2` **Enter** to _Discover owned devices_ the server and client should be listed
### (Step 3) Pair Server and Client
- Type `4` **Enter** to _Provision pair-wise credentials_
- Type `12` **Enter** to _Provision pair-wise credentials_
- Type `0` **Enter** `1` **Enter** to pair the client and server. If you have multiple owned
devices you will have to select the correct devices from the list.
### (Step 4) Restart and Test
The samples should be onboarded and provisioned. Restart the server and client they should discover
each other and run without difficulty.
The samples should be onboarded and provisioned. Restart the server and then the client they should
discover each other and run without difficulty.
Layout of swig folder
=================================================
......@@ -528,10 +472,9 @@ summary of the contents of each directory.
This also contains project files for the Eclipse IDE if user wishes to import the
iotivity-lite code into Eclipse.
- `java_lang`<br />
Contains build scripts needed to generate the Java language binding using SWIG. Some of the
files generated by SWIG will be placed in this directory as well as the
`iotivity-lite-java` directory. With the exception of the scripts for building and
running the samples all commands given in this README are run from the `java_lang` directory.
Contains build scripts needed to generate the Java language binding using SWIG. With the
exception of the scripts for building and running the samples all commands given in this README
are run from the `java_lang` directory.
- `oc_java`<br />
Contains Java files that are used by the SWIG output but not not generated as part of the SWIG
build process. Most of the files are Java interfaces used to handle callbacks and bitmask
......@@ -548,7 +491,7 @@ Eclipse project files
=================================================
Where possible command line build scripts have been provided for building and running the code.
However much of the development was done using the Eclipse IDE. The project files have been
committed so other developers can take advantage of this powerful IDE if they wish.
committed so other developers can take advantage of the Eclipse IDE if they wish.
To open the project files:
- Open Eclipse
......@@ -559,10 +502,6 @@ To open the project files:
- browse to the `<iotivity-lite>\swig` directory click `OK`
- make sure the checkbox for the desired projects is checked. Click `Finish`
Copy the `iotivity-lite-jni` shared object file into the
`<iotivity-lite>/swig/iotivity-lite-java/libs` directory. The eclipse projects have
been setup to search for the library in that location.
Run the unit tests by right clicking on `iotivity-lite` project select `Run As -> JUnit Test`.
Selecting `Run As -> Java Application` will run the command line version of the unit tests.
......@@ -582,17 +521,17 @@ directories in the project. The project structure is:
```
project/
├──libs/
| └── iotivity-lite.jar
├──src/
└── main/
├── AndroidManifest.xml
├── java/
└── jniLibs/
├── armeabi/
│ └── libiotivity-lite-jni.so.so
└── x86-64/
└── libiotivity-lite-jni.so.so
+--libs/
| +-- iotivity-lite.jar
+--src/
+-- main/
+-- AndroidManifest.xml
+-- java/
+-- jniLibs/
+-- armeabi/
| +-- libiotivity-lite-jni.so.so
+-- x86-64/
+-- libiotivity-lite-jni.so.so
```
This structure is reflected in the app `build.gradle` file:
......@@ -648,8 +587,6 @@ To allow these example applications to work, permissions had to be granted in th
Send Feedback
=================================================
The SWIG generated language bindings are still in an early stage. The work is subject to change.
Questions
[IoTivity-Lite Developer Mailing List](https://iotivity-dev@lists.iotivity.org)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment