Difference between revisions of "Lantronix Python Programmers Guide"

From Lantronix Wiki!
Jump to navigation Jump to search
 
Line 118: Line 118:
 
   
 
   
 
==== Running Python Programs ====
 
==== Running Python Programs ====
In order to run the configured Python program the <tt>run python</tt> 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.
+
In order to run the configured Python program the <tt>python run</tt> 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.
 
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.
 
    
 
    
Line 126: Line 126:
 
  (enable)# '''configure'''
 
  (enable)# '''configure'''
 
  (config)# '''applications'''
 
  (config)# '''applications'''
  (config-applications)# '''run python ''<instance>'''''
+
  (config-applications)# '''python run ''<instance>'''''
 
  (config)# '''exit'''
 
  (config)# '''exit'''
 
  (enable)# '''exit'''
 
  (enable)# '''exit'''

Latest revision as of 18:29, 11 May 2015


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 python run 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)# python run <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/.

Develop/Test on Windows/Linux Host

Python programs can be written using one's favorite editor. Most editors that are self-contained and those included within an Integrated Development Environment (IDE) support Python syntax highlighting and coloring to make it quicker to follow the code flow. Once the program is written it can be executed, debugged and tested using either the Python Command Line interpreter or using an IDE such as IDLE, Eclipse or PyDev.

Using Python on Command Line

On the development host, the Python program/script can be tested by running it with the Python Interpreter as shown below

c:\Python27> python.exe helloworld.py
Hello World!

c:\Python27>

Python commands can also be executed directly in the Python shell

c:\Python27>python.exe
Python 2.7.8 (default, Jun 30, 2014, 16:03:49) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> print 'Hello World!'
Hello World!
>>>

Using IDE

An IDE offers many tools that can work cohesively to increase developer productivity. The editors within an IDE offer context-sensitive help, auto-complete, syntax checking and coloring. An integrated debugger that allows the developer to step through the code and trace the execution path is also included.

For example, Pydev (http://pydev.org) is a Python IDE for Eclipse.

Dev ide pydev.png


Create Python Package For Lantronix Devices

Python Modules

Modules in Python are special Python files that can share function definitions with other Python programs. For example:

helloworld.py

def print_hello_world():
        print 'Hello World!'

Using the import command from the Python interpreter or using the import keyword within the Python program, one can import the module and use its functions in other Python programs.

Python Packages

Packages are a way of structuring Python’s module namespace by using dotted module names. For example, the module name A.B designates a sub-module named B in a package named A. The use of packages saves the developer from having to worry about each others module names.

To create a Package for use on Lantronix device, create the following folder structure:

<package name>
    setup.py
    <package name>
        __init__.py
        module.py

The file setup.py has the following structure:

import sys
from distutils.core import setup
setup(name='<package name>',
    version='<package version>',
    description='<package description>',
    url='<url>',
    author='<author name>',
    author_email='<author email>',
    packages=['<package name>'],
    zip_safe=False)

For the helloworld module example, the other package files would include the following:

File __init__.py has the following structure:

from .module import print_hello_world

File module.py has the following structure:

def print_hello_world():
    print 'Hello World!'

To create Python package:

# cd <folder containing setup.py>
# python setup.py sdist

This will create a dist/<package name>-<package version>.tar.gz which can then be installed on the Lantronix device.

NOTE: When using third party modules, additional dependencies may exist. The standard Python distribution provides a tool called modulefinder.py that is useful in this scenario. This tool examines imports in Python programs to build a list of modules that may be used. Please make sure that all dependencies are also installed on the Lantronix device.

To use Python package function from a Python program:

client.py

import <package name>

<package name>.print_hello_world();

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.