Difference between revisions of "Lantronix Python Programmers Guide"

From Lantronix Wiki!
Jump to navigation Jump to search
Line 152: Line 152:
 
* Select and upload Python program using the '''Upload File''' section.
 
* Select and upload Python program using the '''Upload File''' section.
  
[[File:
+
 
 +
[[File:Webui_loading_programs.png]]
 +
 
 +
 
 +
For module packages, use the tar.gz file to upload.
 +
 
 +
 
 +
[[File:Webui_installing_packages.png]]
 +
 
  
 
==== Installing Python Module Packages ====
 
==== Installing Python Module Packages ====
 +
Once the module packages have been uploaded,follow the steps below to install the Python package:
 +
* Navigate to the '''Applications''' menu
 +
* Enter the Python Package name in the '''Install Package from Filesystem''' section
 +
* Click '''Install'''.
 +
 +
 +
[[File:Webui_installed_packages.png]]
 +
 +
 +
The newly installed packages will show up in the list of installed packages and is ready to be used by any Python program.<br>
 +
The '''Installed Packages''' section provides additional metadata such as Version, Summary, File, Supported Python Version, etc. about the list of packages available on the device.
 +
  
 
==== Configure Python Programs ====
 
==== Configure Python Programs ====
 +
In order to configure the Python programs that need to run, follow the steps outlined below:
 +
* Navigate to the '''Applications''' menu on the Web UI
 +
* Enable and Configure specific Script Instance with the desired script file name and optional arguments/parameters, output file
 +
* Configure the appropriate run control options - '''Run on Startup''', '''Run on Shutdown'''
 +
* Enable the script - using the '''Enabled''' checkbox
 +
 +
 +
[[File:Webui_configure_apps.png]]
 +
 +
 +
* Click Submit to commit these changes to the device for persistent and automatic actions based on the configuration.
 +
  
 
==== Running Python Programs ====
 
==== Running Python Programs ====
 +
In order to run the configured program instantly or only when triggered via the '''Run''' command button, follow the steps below:
 +
* Navigate to the '''Applications''' menu on the Web UI
 +
* Enable and Configure specific Script Instance with the desired script file name and optional arguments/parameters, output file
 +
* Click the '''Run''' button next to the Python '''Script ''<instance>''''' to run the program.
 +
  
 +
[[File:Webui_running_programs.png]]
  
  
Line 181: Line 219:
 
=== Python Version Supported ===
 
=== Python Version Supported ===
 
==== Python Language/Runtime ====
 
==== Python Language/Runtime ====
 +
The current supported version of Python runtime on Lantronix devices is '''2.7.3'''.
 +
 
==== Python Standard Library ====
 
==== Python Standard Library ====
 +
Most of the Python standard modules are included in Lantronix Python installation.<br>
 +
Python standard modules '''not''' included are:
 +
* Multimedia services
 +
* Web browser controller
 +
* Microsoft Windows specific services
 +
* Development tools
 +
* bsddb from Database services
 +
* GNU readline interface
 +
* curses (terminal handling)
 +
* Tk graphical user interfaces.
 +
  
 
=== Preinstalled Python Packages ===
 
=== Preinstalled Python Packages ===

Revision as of 06:02, 18 November 2014


Introduction

Overview

This guide introduces developers to the support for the Python runtime on Lantronix line of embedded and ready-to-deploy Intelligent Gateway products. It describes how to load and run Python programs on Lantronix devices, reviews available Python modules including those that expose Lantronix specific APIs and describes sample Python programs for common use cases that provide a head-start in customizing Lantronix Intelligent Gateway platforms.


What is Python?

Python is a programming language that lets you work more quickly and integrate your systems more effectively. It is a dynamically typed, object-oriented programming language offering an elegant syntax and an extendable Python interpreter. This makes it an ideal language for scripting and rapid application development for most applications and specifically connected device applications. The Python interpreter and the extensive standard library are freely available in source or binary form for all major platforms (Windows, Linux\Unix, Mac OS X) and on machine-to-machine (M2M) or Internet of Things (IoT) focused Intelligent Gateway platforms from Lantronix.


Additional Python Reference

The Python Programming Language website (http://www.python.org) is the definitive and official source for all Python information. It also contains additional links to other Python references including other sites, books, etc. For a quick and informal introduction to Python, the tutorial at Python Tutorial is a great start.


Supported Lantronix Products

The following Lantronix products provided integrated Python runtime support.

Support for the following Lantronix products is planned (Alpha Software Available)


Getting Started

This section describes how to create a simple Python program and the steps to run the program on a Lantronix device.

First Program "Hello World"

Write Simple Python Program

In your favorite text editor, create a file named 'helloworld.py', with the following contents:

# Hello World - a simple text output program
def main():
print 'Hello World!'

main()

Transfer Program Onto Lantronix Device

  1. Log in to the Web UI for Lantronix Device. Enter the configured username and password. Default values are admin and PASS.
  2. Using the Filesystem menu option, go to the Browse sub-menu and upload the helloworld.py file to the device.


File transfer getting started.jpg

Run The Program

  1. Navigate to the Applications menu option in the Web UI.
  2. For script 1, enter the script name as helloworld.py and mark the Enable checkbox to enable this script.
  3. Enter the output filename as helloworld.out. This file will be created in the filesystem to capture all stdout output from the script.
  4. Hit the Run button for Script 1 to run the transferred program.


Python application getting started.jpg


Open the output file helloworld.out from the Filesystem -> Browse Menu to check the expected Hello World output from the script.

System Requirements

Integrated Python runtime is available from software version 7.9.0.0 onwards on the supported Lantronix products.
If you have products with software version older than 7.9.0.0, please follow the upgrade instructions for the respective products. The software and the upgrade notes are available from the Lantronix support site at www.lantronix.com/support/downloads.

Recommended Python Version

The version of Python supported on Lantronix PremierWave family of Intelligent Gateway products is 2.7.3. We recommend that you install the same version on your development machine (Windows/Linux).

Using Python on Lantronix Devices

Configuration and control of Python programs can be accomplished by accessing the Command Line Interface (CLI) using Telnet/SSH or serial port. Web configuration UI is accessible via the browser on any Windows/Linux host or on smartphone/tablet. Supported browsers are Firefox, Chrome and Internet Explorer.

Using CLI (Command Line Interface)

The CLI provides a quick and easy way for developers used to working in the Command Prompt on Windows or using the Shell on Linux to interact with the Lantronix devices.

Load Python Programs

To upload Python program to Lantronix device, use FTP on the command line. The following is an example of this procedure at the Linux shell prompt.

#ftp <Lantronix Device IP Address>
-- login --
ftp> put helloworld.py helloworld.py
ftp> exit

For Python module packages, use FTP to transfer the tar.gz package tarball as shown below.

#ftp <Lantronix Device IP Address>
-- login --
ftp> put <python_package>.tar.gz <python_package>.tar.gz
ftp> exit

Installing Python Module Packages

To install the packages, using CLI, please follow the steps provided below.

#telnet <Lantronix Device IP Address>
--login (if enabled)—
> enable
(enable)# configure
(config)# applications
(config-applications)# python install <zip|tar.gz file>
(config)# exit
(enable)# exit

Configure Python Programs

To configure uploaded Python programs to run, a series of commands needs to be entered in the CLI. The example below shows connecting to the CLI via telnet and assumes that Python program helloworld.py was uploaded using the earlier steps.

#telnet <Lantronix Device IP Address>
--login (if enabled) --
> enable
(enable)# configure
(config)# applications
(config-applications)# python <instance>
(config-applications-python:<instance>)# file <python program>.py
(config-applications-python:<instance>)# state enable
(config-applications-python:<instance>)# write
(config-applications-python:<instance>)# exit
(config)# exit
(enable)# exit

Running Python Programs

In order to run the configured Python program the run python is used. The stdout is directed towards the output file (if configured). The Python program is not a sub-process of the CLI process and run in the background. As a result it does not inherit the file descriptors of the CLI process even though the run command is issued via the CLI. This is generally not considered a limitation as most Python programs for connected applications would run independently and use modules that provide network connectivity protocol implementations or specific hardware abstraction functions.

#telnet <Lantronix device IP addresss>
--login (if enabled)—
> enable
(enable)# configure
(config)# applications
(config-applications)# run python <instance>
(config)# exit
(enable)# exit

Additional Available Commands

There are additional commands available for the following functions:

  • parameters <text>
    String of parameters as arguments to the script when it runs
  • output <text>
    Output file name for capturing stdout and debugging messages (print)
  • onstart enable
    Enable script to run on device bootup/startup
  • onstart disable
    Disable script to run on device bootup/startup
  • onshutdown enable
    Enable script to run on device shutdown
  • onshutdown disable
    Disable script to run on device shutdown


Using Web Configuration UI

The Web Configuration UI provides an easy to follow point-and-click mechanism for device configuration. Python programs can be loaded, configured and run through the Web Configuration UI as described below.

The Web Configuration UI is accessed via the Web browser by logging in using the configured password for the admin user.

Load Python Programs

In order to upload the Python programs or module packages to the Lantronix device:

  • Navigate to the Filesystem menu
  • Select the Browse tab.
  • Select and upload Python program using the Upload File section.


Webui loading programs.png


For module packages, use the tar.gz file to upload.


Webui installing packages.png


Installing Python Module Packages

Once the module packages have been uploaded,follow the steps below to install the Python package:

  • Navigate to the Applications menu
  • Enter the Python Package name in the Install Package from Filesystem section
  • Click Install.


Webui installed packages.png


The newly installed packages will show up in the list of installed packages and is ready to be used by any Python program.
The Installed Packages section provides additional metadata such as Version, Summary, File, Supported Python Version, etc. about the list of packages available on the device.


Configure Python Programs

In order to configure the Python programs that need to run, follow the steps outlined below:

  • Navigate to the Applications menu on the Web UI
  • Enable and Configure specific Script Instance with the desired script file name and optional arguments/parameters, output file
  • Configure the appropriate run control options - Run on Startup, Run on Shutdown
  • Enable the script - using the Enabled checkbox


Webui configure apps.png


  • Click Submit to commit these changes to the device for persistent and automatic actions based on the configuration.


Running Python Programs

In order to run the configured program instantly or only when triggered via the Run command button, follow the steps below:

  • Navigate to the Applications menu on the Web UI
  • Enable and Configure specific Script Instance with the desired script file name and optional arguments/parameters, output file
  • Click the Run button next to the Python Script <instance> to run the program.


Webui running programs.png


Development Workflow

This section provides an overview of the development workflow when creating Python programs and packages for use on Lantronix devices.
Since Python is available on a number of platforms, most development for Python can be done on a Windows/Linux host and tested locally too. The Python program can then be transferred to the Lantronix devices for further debugging, testing, packaging and deployment.

The current version of Python installed on Lantronix devices is 2.7.3. We recommend that you install the same version on your development machine. Also, only use the python modules known to be compatible with this version. For download, installation instructions and additional documentation please visit https://www.python.org/.

Command Line Based Workflow

Develop/Test on Windows/Linux Host

Using Python Interpreter Command Line

Using IDE

Create Python Package For Lantronix Devices

Transfer/Run Python Programs on Lantronix Devices

Follow the instructions in the section above on Using Python on Lantronix devices to test and deploy the program on Lantronix devices.

Python Runtime Support

Python Version Supported

Python Language/Runtime

The current supported version of Python runtime on Lantronix devices is 2.7.3.

Python Standard Library

Most of the Python standard modules are included in Lantronix Python installation.
Python standard modules not included are:

  • Multimedia services
  • Web browser controller
  • Microsoft Windows specific services
  • Development tools
  • bsddb from Database services
  • GNU readline interface
  • curses (terminal handling)
  • Tk graphical user interfaces.


Preinstalled Python Packages

PySerial

This module encapsulates the access for the serial port.
More information can be found at: http://pyserial.sourceforge.net/

While using this module for a particular serial port, please ensure that no other applications are using that serial device. Serial port access for standard Lantronix applications, can be disabled using the no protocol command at the 'line menu level in the CLI or via selecting Protocol: None under the Line menu on the Web UI.