Category     

SDK Common Settings used in Sample Code

« Go Back

Information

 
Content

File Details

File Names

In all cases, the file names are case sensitive. So the file "settings.ini" must not be edited as "SETTINGS.INI", nor "Settings.ini". This is a pain under Windows, which loves to capitalize the first letter of new file names. However, just live with it and force the lower case! Fortunately, most development tools (such as PyCharm or notepad++) override this behavior and do not cause such mindless capitalization.

Directory Separators

While Unix/Linux forces use of "/" (forward slash), Python under Windows allows either "/" or "\" (forward or back slash). So in general, your Python code should use the more universal "/" (forward slash). The official way to handle directory paths in Python is as: os.path.join("config", "settings.json"), however this isn't really required if you stick to the Unix/Linux format.

INI = settings.ini

Your source settings files must be INI files (https://en.wikipedia.org/wiki/INI_file), which the official MAKE.PY bundling tool will convert to json for you. The section headers (such as [application]) should be lower case. MAKE.PY handles two distinct "settings.ini" files for each build/make. It first parses global (or shared) settings located in the main code directory, with the name "./config/settings.ini". After this file is converted to Python keyed data, then MAKE.PY looks in your project directory, parsing in the project specific settings which overwrite (or replace) any global settings. For example, if your project is in "network/tcp_echo", the MAKE.PY looks for the file "./network/tcp-echo/settings.ini". If the setting [logging][level] is "info" in the global file, but "debug" in your project file, then the final setting used by the running project is [logging][level] = "debug".

The INI file end-of-line (EOL) doesn't matter, but you should be consistent, so either make the entire INI file Linux style (\n), Windows style (\r\n), or MAC style (\r). Comments must start with a ";" (not "#"), and the spaces around "=" are optional. Leading or trailing white space will be ignored, but should be avoided. Below is an example of an INI. Note that formal comments and white space are discarded, plus at present fancy features like "hierarchies" are not supported.
; example app settings
[application]
name=tcp_echo
path = network/tcp_echo
; the following settings are special for your example/sample app
[tcp_echo]
host_port = 9999

JSON = settings.json

The final settings packed into TAR.GZIP archives will be in JSON format, within which all white space is ignored. Assume the keys are all case sensitive, and the sample code shall be using lower case name with "_" characters to separate words. Below is an example, and although JSON has no official support for COMMENTS, some of the automated tools shall include ["_comment"] keys. {
    "application": {
        "_comment": "Settings for the application being built.",
        "name": "tcp_echo",
        "path": "network/tcp_echo"
    }
    "tcp_echo": {
        "host_port": "9999",
    }
}

INI File Sections

Expected Sections

The MAKE.PY and various common tools expect certain settings and INI sections, including:
  • Section [application] - specific settings for you application. If you have multiple application, you likely need to change these settings.
  • Section [logging] - settings used to channel your LOGGING/TRACE output to a Syslog server.
  • Section [router_api] - settings required by MAKE.PY to load code and do actions on your local Cradlepoint router under development.
The MAKE process will force the section names to lower-case.

Your Settings

MAKE.PY converters the settings.ini to settings.json, creating a simple two-level hierarchy – look back at the example settings.json file above. This allows you to add as any sections to settings.ini as you wish, and they will be moved to the settings.json file. If you use the SDK tools, then your application will receive a Python dictionary which, using the data above, will look like this. Even your custom "host_port" setting is there:
  • settings["application"]["name"] = "tcp_echo"
  • settings["application"]["path"] = "network/tcp_echo"
  • settings["tcp_echo"]["host_port"] = "9999"
All settings will be treated as strings, so make sure to convert to numeric or boolean as required.

Group: application

These settings affect your specific project, so generally are placed in your application sub-directory. However, you can place any common or shared settings into the ./config/settings.ini

description : str, optional

  • A simple description – can include unicode/UTF8.
  • Example: description=Basic TCP echo server and client
  • Default = None

firmware : str, required

  • Define the minimum level of firmware required in a Cradlepoint router. The format is a string of two integers – a "major" and "minor" portion. This format is assumed by other portions of the SDK/App sub-system – do NOT add text tags like "-beta", nor other levels such as 6.1.0.1.
  • Example: firmware=6.1

name : str, required

  • The actual application name, which should avoid foreign or special character sets The "_" or underscore is okay. This name shall be used to build the various manifest and archive files.
  • Example: name=tcp_echo

path : str, optional

  • The relative path to your project or application code. Avoid using if the "path" matches your application "name". For sub-directories, use the Unix/Linux style back-slash, plus do not use foreign or special characters.
  • Example: name=tcp_echo
  • Default = setting ["name"]

restart : bool, optional

  • Define if your application is to be restarted if it exists.
  • Example: restart=true
  • Default: True

uuid : str, required

  • To avoid duplicating file names on the Cradlepoint router, a standard uuid is used, as defined by https://docs.python.org/3.3/library/uuid.html. If you do not include one in your INI file, then a random one will be automatically generated an inserted into your INI file (the one in your project directory).
  • Example: uuid=7042c8fd-fe7a-4846-aed1-e3f8d6a1c91c
  • Default = a random one is created

version : str, optional

  • The application version is a string of two integers – a "major" and "minor" portion. This format is assumed by other portions of the SDK/App sub-system – do NOT add text tags like "-beta". Adding the "-i" option to MAKE.PY during the build option, causes it to automatically increment the minor number and rewrite this, but only to the INI file in your application sub-directory.
  • Example: version=1.26
  • Default = "1.0"

Group: logging

These settings affect the module "cp_lib\cp_logging", which helps properly define a Python LOGGING instance compatible with Syslog and Cradlepoint routers. While this section is generally a global setting in your ./config directory, you can override these settings on a project by project basis.

level : int or str, optional

  • The output level as applied to the standard Python logging module, this can be:
    • the common names in the following list ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"). These are not case sensitive, so "debug" == "Debug" == "DEBUG".
    • the numeric value in the following list (50, 40, 30, 20, 10), although any number which the logging module accepts can be used.
  • Example: "level=debug"
  • Default = "INFO" or 20

log_file : str, optional

  • Define a log file for a rotating file on your PC only. The name is submitted to the LOGGING module. When your code runs on a Cradlepoint router, this setting is IGNORED and no file is logged.
  • Example: log_file=trace.txt
  • Default = None/disabled

name : str, optional

  • When the logger is created, it uses this name in the output trace line.
  • Example: name=doit
  • Default = the Python "logging" module default name

syslog_ip : str, optional

  • Defines the IP address of a local syslog server. Leave unset, or set to None to disable. If you need a syslog server, you can use ./tools/syslog_server.py, which alos allow you to add patterns to ignore.
  • Example: syslog_ip=192.168.0.10
  • Default = None/disabled

syslog_port : int, optional

  • The UDP port used by your Syslog server. This setting is ignored if syslog_ip is none.
  • Example: syslog_port=514
  • Default = 514

syslog_facility : int, optional

  • Optionally allows to change the PRI number, which allows easier filtering in a Syslog server. The parsing of strings is not allowed – use a number only.
  • Example: syslog_facility=22
  • Default = LOG_LOCAL0 from logging module

Group: router_api

These settings are required for the stock MAKE.PY, but may be used by other functions. You would normally place these settings in your global ./config/settings.ini file.

local_ip : str, required

  • The IP address of a Cradlepoint router under development.
  • Example: local_ip=192.168.0.1

password : str, required

  • The password for local access to your Cradlepoint router under development. The Cradlepoint default is the last part of the MAC address, however passwords are case sensitive, so hex characters should be lower case.
  • Example: password=441b1702

user_name : str, optional

  • The user name for local access for your Cradlepoint router under development.
  • Example: user_name=admin
  • Default = admin

interface : str, optional

  • string name of the interface for the router - used on a multi-homed system to select 1 of N interfaces. For example, if you have added a second Ethernet port (or USB to Ethernet module), then your computer can have more than one IP address and be linked to more than 1 subnet. Under Windows, the default is "Local Network Connection".
  • Example: interface=Local Addin ENet

Group: startup

These settings are used by the stock SDK Sample "main.py":

boot_delay_max_seconds : int, optional

  • By default, "main.py" delays until the router appears to be running in steady-state. This delay ends after this time delay regardless of router status.
  • Example: boot_delay_max_seconds=120
  • Default = 300 seconds (or 5 minutes)

boot_delay_for_time : bool, optional

  • When the router first boots, it takes time for NTP or other methods to obtain valid system time. Before this delay, the return value of Python time.time() is useless. After all, what use is logging a room temperature stamped as 01-01-1970 for the first few minutes of operation? Set this to false if you do not care about seeing time as 1970.
  • Example: boot_delay_for_time=false
  • Default = True

boot_delay_for_wan : bool, optional

  • When the router first boots, it will takes time for outgoing IP connections to be valid. Before this delay, outgoing connection requires are GUARANTEED to fail, and what is the use of starting your cloud-seeking application in fault/disconnected mode for the first few minutes of operation? Set this to false if you do not care to delay for WAN access.
  • Example: boot_delay_for_wan=false
  • Default = True

exit_delay : int or str, optional

  • By default, "main.py" exits as soon as your RouterApp.run() exits, which causes the Router to attempt to restart rapidly. This optional allows you to delay this exit. Note that any time delay is coarse, roughly +/- 10 seconds.
  • Example: exit_delay=120, means delay at least 120 seconds (2 minutes)
  • Example: exit_delay=none, means no delay, exit immediately
  • Example: exit_delay=forever, means never delay. Use with caution! Most useful during test or development.
  • Default = None, so no added delay to exit

 
Knowledge Home | Product