Cradlepoint NCOS SDK 3.0
-Application Developers Guide
Cradlepoint’s NetCloud OS (NCOS) SDK provides the ability to
-customize the functionality of Cradlepoint devices with applications written in
-Python. Python applications written with the SDK are securely downloaded to the
-device and enabled using NetCloud Manager (NCM). Cradlepoint’s
-SDK allows for extending and enhancing the functionality of Cradlepoint
-devices, FOG computing, and managing IoT devices.
For the scope of this document, NetCloud OS (NCOS) Apps are
-limited to the non-privileged Python scripts. Supported functionality includes
-the following:
· Standard TCP/UDP/SSL socket servers
-function on ports higher than 1024.
· Standard TCP/UDP/SSL socket client to other
-devices (or the device as 127.0.0.1/localhost).
· Access to serial ports via the PySerial module, including native and USB-serial ports.
· Ability to PING external devices.
· UI Extensibility (i.e. Hot Spot splash page or
-other UI WEB pages)
· Access to the NCOS API (aka: status and control
-tree data).
· USB Memory device file access.
· Any form of natively-compiled
-or kernel-linked code (.pyc, .so files)
· Any function requiring privileged (or root)
-permissions.
Please refer to the Please refer to the SDK Support Statement.
+color:#015BA7'>SDK Support Statement.
Cradlepoint publishes and supports the SDK toolkit for customers and partners
to build their own applications. Cradlepoint neither develops any custom SDK
@@ -3758,43 +196,34 @@
NCOS SDK Applications can introduce security and other potential issues when
not carefully engineered. Test your code thoroughly before deploying it to
-production devices.
For ease of development and debugging, an application can be
-directly installed into a device that has been placed into Developer Mode. Once
-the application is fully debugged and ready for deployment, it can be installed
-via NCM at the group level.
Cradlepoint has a simplified SDK, written in Python, that builds
-and creates an app package. The SDK, along with sample applications, is located
-in the Cradlepoint has a simplified SDK,
+written in Python, that builds and creates an app package. The SDK, along with
+sample applications, is located in the Cradlepoint SDK GitHub repository.
+style='font-size:9.0pt;font-family:"Arial",sans-serif;color:#015BA7'>Cradlepoint
+SDK GitHub repository.
For app development, the SDK is used to install, start, stop, uninstall, and
check the status of an application in a locally-connected development device.
@@ -3802,2381 +231,1646 @@
for production deployment. Application development can be done on Linux, OS X,
and Windows operating systems with the same SDK.
-This document is specifically written for SDK version 3.0 and above.
Cradlepoint has a Developer Community Portal.
Our Customer Community has articles related to the SDK, as well
-as forums to leverage knowledge, share, and collaborate with other developers.
-This forum is actively monitored by Cradlepoint to answer your questions.
NCOS application are written in Python. However, for storage space
-and security purposes, the NCOS Python environment is a subset of a typical
-Python installation on a computer. A list of the installed Python modules in an
-NCOS device is available by installing and running the sample app named “python_module_list” that is included with the SDK sample
-apps. The “python_module_list” application writes the
-names of the installed Python modules on a device to that device’s log.
+font-family:"Arial",sans-serif;color:black'>NCOS application are written in
+Python. However, for storage space and security purposes, the NCOS Python
+environment is a subset of a typical Python installation on a computer. A list
+of the installed Python modules in an NCOS device is available by installing
+and running the sample app named “python_module_list” that is included with the
+SDK sample apps. The “python_module_list” application writes the names of the
+installed Python modules on a device to that device’s log.
New Python files can be added to your application, but their dependencies must
also adhere to the NCOS Python environment. These new Python files/modules can
be copied to the main application directory or can be installed using pip. If
-pip is used, any 'egg' or 'dist' directories can be
-deleted. They are not required for functionality and will just use up memory
-unnecessarily when installed into the NCOS device.
+pip is used, any 'egg' or 'dist' directories can be deleted. They are not
+required for functionality and will just use up memory unnecessarily when
+installed into the NCOS device.
-Example pip command:
pip(3) install --ignore-install --target=<path to application
-directory> <module name>
pip(3) install --ignore-install +--target=<path to application directory> <module name>
+font-family:"Arial",sans-serif;color:black'>
Note: Use pip on Windows and pip3 on Linux or OS X.
-
Use the following sections to set up your development environment
-to work with the Cradlepoint SDK.
Download the SDK and sample apps from Download the SDK and sample apps
+from https://github.com/cradlepoint/sdk-samples. Below are the setup instructions for:
Note: Command line commands must be performed in the order they
-appear.
1.
-Install Python 3.7 or
-newer from 1. Install
+Python 3.7 or newer from python.org.
2.
-Add Linux development
-libraries by using the following commands:
sudo apt-get install libffi-dev
sudo apt-get install libssl-dev
sudo apt-get install sshpass
sudo apt-get +install libffi-dev
+ +sudo apt-get +install libssl-dev
+ +sudo apt-get +install sshpass
3.
-Install Python libraries
-by using the following commands.
sudo apt-get install python3-pip
sudo apt-get +install python3-pip
-pip3 install requests
pip3 install +requests
-pip3 install pyopenssl
pip3 install +pyopenssl
-pip3 install
-cryptography
pip3 install +cryptography
Useful tools
PyCharm (community version is free): PyCharm (community version is
+free): https://www.jetbrains.com/pycharm/download/#section=linux.
1.
-Install Python 3.7 or
-newer from 1. Install
+Python 3.7 or newer from python.org.
2.
-Install HomeBrew for package updates by using the following
-commands:
/usr/bin/ruby --e "$(curl -fsSL 2. Install +HomeBrew for package updates by using the following commands:
+ +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
3.
-Install these required
-libraries by using the following commands:
brew install openssl
brew install http://git.io/sshpass.rb
brew install +openssl
+ +brew install http://git.io/sshpass.rb
4.
-Install the Python
-libraries by using the following commands:
pip3 install -U pip
pip3 install -U +pip
-pip3 install requests
pip3 install +requests
-pip3 install pyopenssl
pip3 install +pyopenssl
-pip3 install
-cryptography
pip3 install +cryptography
Useful tools
· PyCharm (community version is free): · PyCharm
+(community version is free): https://www.jetbrains.com/pycharm/download/#section=macOS.
1.
-Install Python 3.7 or
-newer from 1. Install
+Python 3.7 or newer from https://www.python.org/downloads/windows/.
2.
-The SDK requires OpenSSL
-tools to generate digital signatures. Go to https://slproweb.com/products/Win32OpenSSL.html and download the 'Light' version based on
-your machine (i.e. Win64 or Win32). Run the executable after it is downloaded
-to install OpenSSL.
3.
-Open a terminal window
-and use the following commands to install the Python libraries.
python -m pip install -U
-pip
python -m pip install pyserial
python -m pip install
-requests
python -m pip install pyopenssl
Useful tools
python -m pip +install -U pip
+ +python -m pip +install pyserial
+ +python -m pip +install requests
+ +python -m pip +install pyopenssl
+ +Useful tools
· Putty: http://www.putty.org/
· PyCharm (community version is free): · PyCharm
+(community version is free): https://www.jetbrains.com/pycharm/download/#section=windows.
· 7-zip: http://www.7-zip.org/
· MarkdownPad: http://markdownpad.com/
Use the following sections to learn about how Cradlepoint SDK apps
-are structured and how to build and debug your own SDK app.
Below is the directory structure for the SDK and sample
-applications. The BOLD items are modified or created by the
-developer. The other files are used by the SDK or are referenced by the other
-files.
· sdk-samples-master (directory)
· app_template_csclient (directory for the application)
· tools (directory)
· bin (directory)
· package_application.py - Used by SDK.
· validate_application.py - Used by SDK.
· pscp.exe - An executable use on Windows by the
-SDK.
· sdk_setting.ini - Used by the SDK and contains the
-settings for building the app and connecting to the local NCOS device.
· make.py – Python script used by the SDK to build
-and install apps and check app status.
· NCOS_SDK_Application_Development_Guide.html
· NCOS_APIs_for_Applications.html
Based on the sdk_setting.ini file, the make.py script builds all
-files located in the app_name directory
+font-family:"Arial",sans-serif;color:black'>Based on the sdk_setting.ini file,
+the make.py script builds all files located in the app_name directory
into a tar.gz package that can then been installed into the
device. This installation is performed either directly into the device (if in
-DEV mode) or via NCM for grouped devices.
An NCOS application package, which is a tar.gz archive,
-consists of a set of files that includes the Python script, start/stop scripts,
-initialization files, along with manifest and signature files. This package of
-files is built by the SDK based on the sdk_settings.ini. Some of these files,
-like the manifest and signature files, are created by the make.py tool. Others
-are created by the application developer. Below are the example contents for
-a tar.gz archive created for a NCOS application. The BOLD items
-are modified or created by the developer. The other files are used by the SDK
-or are referenced by the other files.
· app_template_csclient (directory)
· METADATA (directory)
· MANIFEST.json - Contains a file list along with hash
-signatures and other app the package initialization data.
· SIGNATURE.DS - A signature file for the app
-package.
· app_template_csclient.py - The application Python file.
· csclient.py - Python file containing the EventingCSClient()
-class, with methods for interacting with the NCOS API.
· package.ini – Package and app settings.
· start.sh - The script run when the app is started.
· stop.sh - The script run when the app is stopped. This is not
-required unless one needs a specific action preformed when the application is
-stopped.
csclient.py
A python file containing the EventingCSClient() class with methods for interacting with the NCOS API.
Import the class and instantiate it by passing the string name of
-your app as the only argument. The app
-name is used to identify the app when writing logs or sending custom alerts. In the below example, the EventingCSClient() class is
-instantiated as “cp” for simplified syntax:
from csclient import EventingCSClient
cp = EventingCSClient(‘app_template_csclient’)
The EventingCSClient() class, now instantiated as cp, has the following methods
-for interacting with the NCOS API:
· .log() – writes an info level system log
· Accepts log text (string)
· Usage example:
cp.log(‘This is my log text!’)
· +.log() – writes an info level system log
+ +Accepts log +text (string)
+ +Usage +example:
+ +cp.log(‘This is my log text!’)
01:43:33 PM INFO My_App
-This is my log text!
· .get() – gets a value from the NCOS API
· Accepts NCOS Path (string)
· Returns requested value (no need to specify
-“data” key)
· Usage example – get system ID and log it:
system_id = cp.get('config/system/system_id’)
· +.get() – gets a value from the NCOS API
+ +Accepts NCOS +Path (string)
+ +Returns +requested value (no need to specify “data” key)
+ +Usage +example – get system ID and log it:
+ +system_id = cp.get('config/system/system_id’)
cp.log(system_id)
11:22:17 AM INFO my_app
-AER2200-AER
· .put() – put a value to the NCOS API path
· Accepts a path (string) and payload (accepts
-JSON) and puts the payload in the path
· Usage example – set system ID:
cp.put(‘config/system/system_id’,
-‘MyRouter’)
· .alert() – Sends a custom NCM alert
· Accepts alert text (string)
· Usage example:
cp.alert(‘This is my alert text!’)
· +.put() – put a value to the NCOS API path
+ +· +Accepts a path (string) and payload (accepts JSON) and puts the +payload in the path
+ +· +Usage example – set system ID:
+ +cp.put(‘config/system/system_id’, +‘MyRouter’)
+ +· +.alert() – Sends a custom NCM alert
+ +Accepts +alert text (string)
+ +Usage +example:
+ +cp.alert(‘This is my alert text!’)
Cradlepoint NetCloud: Custom Alert
Alert Name Custom
-Alert
Description app_template_csclient This is my alert text!
MAC Address 00:30:44:36:57:B1
Device Name TLAB 900
Group Name
Timestamp 2020-02-14
-15:10:12 MST
· .post() – create a new list item
-in the NCOS API
· Accepts a path (string) and payload (JSON) and
-creates a new list item.
· Usage example – add a user:
cp.post('config/system/users', {'username': ‘MyUser’, 'password': ‘MyPass’,
-'group': 'admin'})
· .delete() – delete a value from the NCOS API
· Accepts a path (string) to a value to delete
· Usage example – delete a LAN (default guestLAN):
cp.delete(‘config/lan/1’)
· .register() – register a function for callback on an API value change
· A callback is a “push” function where you tell
-NCOS to call your function when a specific API value changes. The path and value are passed to your
-function to be handled as necessary.
· Requires the following 3 positional arguments
-(action, path, function):
· action or method (string) such as ‘put’
· path to the value (string)
· function to call – do not include parenthesis. When the path receives the action,
-it will call your function and pass the path and value to
-it.
· +.post() – create a new list item in the NCOS +API
+ +Accepts a +path (string) and payload (JSON) and creates a new list item.
+ +Usage +example – add a user:
+ +cp.post('config/system/users', +{'username': ‘MyUser’, 'password': ‘MyPass’, 'group': 'admin'})
+ +· +.delete() – delete a value from the NCOS API
+ +Accepts a +path (string) to a value to delete
+ +Usage +example – delete a LAN (default guestLAN):
+ +cp.delete(‘config/lan/1’)
+ +· +.register() – register a function for callback on an API +value change
+ +A callback +is a “push” function where you tell NCOS to call your function when a specific +API value changes. The path and value are passed to your function to be +handled as necessary.
+ +Requires the +following 3 positional arguments (action, path, function):
+ +· +action or method (string) such as ‘put’
+ +· +path to the value (string)
+ +· +function to call – do not include parenthesis. When the path +receives the action, it will call your function and pass the path +and value to it.
· Usage example – call a function when the primary
-WAN device changes:
def wan_change(path, value, *args):
cp.log(f'Primary WAN UID = {value}’)
cp.register('put', '/device/wan/connection/primary', wan_change)
·
-Your
-function must expect the following positional arguments (path, value, *args):
· Path·
+Path is the API path to the key, or field, that you registered for
-callback on.
· Value is the current value of the key in the path
· *args contains dynamic arguments
· return completes the function.
package.ini
+font-family:"Arial",sans-serif;color:black'>package.ini
This initialization file contains information and about the application and
items that affect installation and execution. This information is shown in
-/status/system/sdk within the NCOS config store for
-installed apps.
+/status/system/sdk within the NCOS config store for installed apps.
-For example:
[hello_world]
uuid=7042c8fd-fe7a-4846-aed1-e3f8d6a1c91c
vendor=Cradlepoint
notes=Hello World Demo
-Application
firmware_major=7
firmware_minor=1
auto_start=true
restart=false
reboot=true
version_major=1
version_minor=0
[hello_world]
+ +uuid=7042c8fd-fe7a-4846-aed1-e3f8d6a1c91c
+ +vendor=Cradlepoint
+ +notes=Hello World Demo Application
+ +firmware_major=7
+ +firmware_minor=1
+ +auto_start=true
+ +restart=false
+ +reboot=true
+ +version_major=1
+ +version_minor=0
· [hello_world]
This must contain the name of the application. In this example, hello_world is the application name.
· uuid
Every app must contain a universally unique identifier (UUID). If
-left blank, the make.py “build” action will generate and populate UUID for the
-app.
· vendor
This is the vendor name for the app.
· notes
Add notes to describe the app or anything else.
· firmware_major and firmware_minor
This is the version of NCOS that the app was orginially
-written to work with. Information only.
· auto_start
If set to 'true', the app will automatically start after
-installation.
· restart
If set to 'true', the application will be restarted if it dies or
-is not running. If false, the device will not attempt to restart the
-application.
· reboot
If set to 'true', the application will be started following a
-device reboot. Otherwise, it will not be restarted.
· version_major and version_minor
This contains the app version. This must be incremented for any
-new production app used installed via NCM. It will not re-install the same
-version that already exists in the device.
+font-family:"Arial",sans-serif;color:black'>
start.sh
This script is executed to start the application in the device. It contains the
command to start the Python script and pass any arguments if needed.
-For example:
#!/bin/bash
#!/bin/bash
-cppython hello_world.py
cppython hello_world.py
stop.sh
+font-family:"Arial",sans-serif;color:black'>stop.sh
This script is executed when the application is stopped in the device. It
contains the command to stop the Python script and pass any arguments. This is
not required unless one needs a specific action preformed when the application
is stopped.
-For example:
#!/bin/bash
#!/bin/bash
-cppython hello_world.py
cppython hello_world.py
-
make.py
+font-family:"Arial",sans-serif;color:black'>
The SDK includes a Python make.py file that is compatible for Windows, Linux
-and OS X platforms.
make.py actions are:
default (i.e. no action given): Print a help file
clean: Clean all project
+font-family:"Arial",sans-serif;color:black'>clean: Clean all project
artifacts. To clean all the apps, add the option "all" (i.e. clean
-all).
build or package: Create the app archive tar.gz file. To build all the apps, add
-the option "all" (i.e. build all). Any directory containing a
-package.ini file is considered an app.
status: Fetch and print
-current app status from the locally connected device.
install: Secure copy the app
-archive to a locally connected device. The device must already be in SDK DEV
-mode via registration and licensing in NCM.
+font-family:"Arial",sans-serif;color:black'>install: Secure
+copy the app archive to a locally connected device. The device must already be
+in SDK DEV mode via registration and licensing in NCM.
Note: A 'Connection reset by peer' error displays even when the application
is successfully copied to the device. This occurs when the device drops the
-connections after the file copy is complete.
start: Start the app on the
-locally connected device.
stop: Stop the app on the
-locally connected device.
uninstall: Uninstall the app from
-the locally connected device.
purge: Purge all apps from
-the locally connected device.
uuid: This will create a new UUID for the app and write it to the
-package.ini file.
unit: Run any unit tests
-associated with selected app.
system: Run any system tests
-associated with selected app.
help: Print the help
-information.
+font-family:"Arial",sans-serif;color:black'>
make.py usage
All SDK functions are contained in the make.py Python file. While this
executable is the same regardless of the workstation platform, the Python
-command is not. Use the following Python command based on your platform:
· Linux or OS X:
python3
· Windows:
python
The command structure is:
python(3) make.py <action>
python(3) make.py <action>
The make.py usage is as follows:
1.
-Update the
-sdk_setting.ini file based on your needs.
Example:
[sdk]
app_name=hello_world
dev_client_ip=192.168.0.1
dev_client_username=admin
dev_client_password=44224267
[sdk]
+ +app_name=hello_world
+ +dev_client_ip=192.168.0.1
+ +dev_client_username=admin
+ +dev_client_password=44224267
2.
-Build the application
-package:
python(3) make.py build
Packaging hello_world
python(3) +make.py build
+ +Packaging +hello_world
3.
-Test connectivity with
-your device via the status target:
python(3) make.py status
{
"success": true,
"data": {
"service":
-"started",
"summary": "Service
-Started",
"mode": "devmode",
"apps": []
}
}
python(3) +make.py status
+ ++ +
{
+ ++"success": true,
+ ++"data": {
+ ++"service": "started",
+ ++"summary": "Service Started",
+ ++"mode": "devmode",
+ ++"apps": []
+ +}
+ +}
4.
-Install the application
-on your device:
python(3) make.py install
Installing
-hello_world.tar.gz in NCOS device 192.168.0.1.
Warning: Permanently
-added '192.168.0.1' (RSA) to the list of known hosts.
Received disconnect from
-192.168.0.1 port 22:11: Bye Bye
Disconnected from
-192.168.0.1 port 22
lost connection
python(3) +make.py install
+ ++ +
Installing +hello_world.tar.gz in NCOS device 192.168.0.1.
+ +Warning: +Permanently added '192.168.0.1' (RSA) to the list of known hosts.
+ +Received +disconnect from 192.168.0.1 port 22:11: Bye Bye
+ +Disconnected +from 192.168.0.1 port 22
+ +lost connection
5.
-Get the application
-execution status from your device:
python(3) make.py status
{
"success": true,
"data": {
"service":
-"started",
"summary": "Service
-Started",
"mode": "devmode",
"apps": [
{
"_id_":
-"8a7f79cb-b11b-44bc-bd33-0f4ab3f06d60",
"app": {
"uuid":
-"8a7f79cb-b11b-44bc-bd33-0f4ab3f06d60",
"name": "hello_world",
"date":
-"2020-03-09T14:15:24.936508",
"restart": true,
"reboot": true,
"auto_start":
-true,
"vendor":
-"Cradlepoint",
"version_major":
-0,
"version_minor":
-1
},
"state":
-"started",
"summary":
-"Started Application"
}
]
}
}
python(3) +make.py status
+ ++ +
{
+ ++"success": true,
+ ++"data": {
+ ++"service": "started",
+ ++"summary": "Service Started",
+ ++"mode": "devmode",
+ ++"apps": [
+ +{
+ ++"_id_": "8a7f79cb-b11b-44bc-bd33-0f4ab3f06d60",
+ ++"app": {
+ ++"uuid": "8a7f79cb-b11b-44bc-bd33-0f4ab3f06d60",
+ ++"name": "hello_world",
+ ++"date": "2020-03-09T14:15:24.936508",
+ ++"restart": true,
+ ++"reboot": true,
+ ++"auto_start": true,
+ ++"vendor": "Cradlepoint",
+ ++"version_major": 0,
+ ++"version_minor": 1
+ ++},
+ ++"state": "started",
+ ++"summary": "Started Application"
+ +}
+ +]
+ +}
+ +}
+ ++ +
+ +
Application debugging is accomplished with the use of system logs.
-You can also view logs via CLI commands when logged into the NCOS device console.
-This console is available by logging into the device with SSH or by opening a
-console from the device admin pages.
+font-family:"Arial",sans-serif;color:black'>Application debugging is
+accomplished with the use of system logs. You can also view logs via CLI
+commands when logged into the NCOS device console. This console is available by
+logging into the device with SSH or by opening a console from the device admin
+pages.
-Use the following steps to open the device console from the device admin pages:
1.
-Click System.
2.
-Click System
-Control.
3.
-Click Device Options.
4.
-Click the Device
-Console button.
log (displays logs in
-the terminal window)
log -f (continuously
-displays log entries as they are written)
log -s <text>
-(search for logs that contain <text> and displays them)
log -s -i <text> (search for logs that contain <text>
-but case insensitive)
log clear (clears the
-log buffer)
help log (display the
-log command options)
log (displays +logs in the terminal window)
+ +log -f +(continuously displays log entries as they are written)
+ +log -s <text> +(search for logs that contain <text> and displays them)
+ +log -s -i +<text> (search for logs that contain <text> but case insensitive)
+ +log clear +(clears the log buffer)
+ +help log +(display the log command options)
+ ++ +
+ +
To install an application directly to the device without using
-NCM, the NCOS device must be placed in DEV mode. One would
-typically debug and test an application using DEV mode prior
-to using NCM for installation. DEV mode allows for quicker and
-easier testing and debugging. Instructions for setting up an NCOS device
-for DEV mode are in the article To install an application directly
+to the device without using NCM, the NCOS device must be placed in DEV mode.
+One would typically debug and test an application using DEV mode
+prior to using NCM for installation. DEV mode allows for
+quicker and easier testing and debugging. Instructions for setting up an NCOS
+device for DEV mode are in the article NCOS: SDK Enable
-Developer Mode.
NCM is used to securely deploy applications to devices at the
-group level. If an application tar.gz package is uploaded to NCM and then
-assigned to an NCOS device group, NCM securely downloads and installs the
-application to the devices within the group. For security, the application
-files are not user accessible within NCM or devices. That is, one is not able
-to download the application from the device or NCM.
-
·
-Cradlepoint SDK GitHub repository
·
-SDK and Sample Applications
·
-Cradlepoint · Cradlepoint Developer Community Portal
·
-· Cradlepoint Cradlepoint Customer Community
·
-· Cradlepoint
-Developer/API Site
·
-7-zip
·
-MarkdownPad