Search

Register

Thanks for signing-up! You will receive an email with further instructions to activate your account!

username already taken
You already have an account? .

Login

Forgot password?
Don't have an account yet? Register now for using the UI-Designer and the forum or creating projects.

Documentation

This section describes the JSON structure used to store configurations. In most cases, using theUI Designer should do anything you want. In the UI-Designer, there is also a small help icon ( ) beside every attribute showing a small explanation on mouse-over.

Don't wanna read?

Check out the short introduction on youtube!

 

Short API-like auto-generated docs

See the auto-generated docs for getting a quick overview over available attributes.

General Remarks

The App is called NetIO, but the name displayed on your device is just 'Controller'. There is also no way for me to make the name or the App-Icon customizable. If you would like to have a totally customized App, please write me and I can build a custom App (oh this is gonna be expensive!)
Since there is no security implemented on HTTP, UDP and TCP connections, I recommend to use a VPN connection if using the App from outside your local network. If you are using HTTPS requests, everything will be encrypted.

 

Handling multiple configuration files and sync with online UI Designer

When seeing the first page, a swipe to the right opens the configuration menu on the left. Enter your UI-Designer username and password to connect to your account and sync the online stored configurations. Clicking a configuration loads the according configuration. Once all configurations are synced, the app caches them to be able to load without an internet connection. Swiping to the left will hide the list.

Testing

If you want to test the iPhone/iPad/Android application, simply start a socket server on your computer like described in the Get Started Section.

 

How does the app work?

The app renderes different items on the screen. Every item which can communicate over connections will send a string over this connection with an '\n' attached to it (other terminations can be defined). After sending a defined command, the app waits for a response which can be everything (e.g. 'ok', 'done' or 'ack\n'). After receiving this response, the app will continue sending commands from its internal queue. So: all commands are sent synchronously! If you write your own program, keep this in mind. If the connection is too slow and the internal sending queue exceeds 30 commands, an error ERR1 will be returned and displayed on the items.

Configuration

This is the overall JSON structure. It contains some global information and all pages. Every page contains an items Array, which specifies all Buttons/Labels/Sliders/Switches.

The connections array defines multiple connection details which can be used by items and pages. The connection definition on page-level is used for all buttons on this page except these which have its own connection attribute specified. The items array is a collection of all items like buttons, labels, sliders or switches. All items are rendered in the order of this array

The string specified in the sendOnAppear attribute will be sent everytime a page appears. On the iPhone/Android when the according page-button is pressed and on the iPad when the page appears on the screen after scrolling.

The fitToScreen attribute is only available on Android. If set, all defined sizes will be scaled and adapt to the resolution of the device.

Haptic feedback can be enabled for Android devices for performing a short vibration on button and switch touch.

 
    {
        "type": "NetIOConfiguration",
        "version": 2,
        "description" : (string),
        "name": (string),
        "device": (string),
        "navigation": "fix" | "collapsible",
        "pagebuttonwidth": "static" | "dynamic",
        "style": "flat" | "plastic",
        "navBackground": (string) #r,g,b
        "connections" : [],
        "orientation": "landscape" | "portrait"  #ipad only
        "pages": [
            {
                "name" : (string),
                "label" : (string),
                "connection" : (string) #name of defined connection used for buttons
                "sounds" : "active" | "inactive" | "keyboardsetting",
                "hapticFeedback" : (bool),
                "sendOnAppear" : (string),
                "fitToScreen" : (bool), #android only
                "width": (int),
                "height": (int),
                "textcolor": (string), # r,g,b
                "background": (string) # r,g,b or *.png
                "items" : []
            }
        ]
    }
    

Connections

A connection is a description of a connection which can be used by items all over the application. NetIO supports four different kind of connections:

  • TCP opens a socket to the specified host and port, use the format attribute to send/receives strings or binary data.
  • UDP sends and receives all commands over UDP. UDP is useful for simple applications.
  • HTTP calls URLs on a webserver, it uses the host, the port and a particular command to create a URL: http://{host}:{port}{command} To enable Basic Authentication, add the username and password attribtues.
  • HTTPS works just like HTTP but uses a secure SSL connection

 

It is possible to define multiple connections that are handled in parallel in the application. Keep in mind, that the initialsend will be executed everytime the app enters the foreground, because a new connection is being established. The default sendTermination string is "\n" and will be added to every command automatically. With this attribute, you can append whatever is needed by the receiving hardware (UDP/TCP). The same applies for receiveTermination, the app reads from the connection until it receives the receiveTermination characters.

Event-Based connections

If you define the eventBased attribute on a TCP or UDP connection, the app will read whatever data comes via the connection without having send something beforehand. This means, the app can react on events coming from the hardware wihtout explicitly requesting an update. UDP connections have this option always enabled. Once the app receives data, all items will get the data to process it. This means, every item would need to filter with parseResponse (see far below on this page) to check if the data is suitable for itself.

 
  {
      "name" : (string),
      "host" : (string),
      "port" : (uint),
      "timeout" : (uint),
      "initialsend" : (string) 
      "format" : "string" | "hex",
      "sendTermination" : (string),
      "receiveTermination" : (string),
      "protocol" : "tcp" | "udp" | "http" | "https",
      "eventBased" : (bool)
  }

Items

Every item needs a type attribute which indicates the type of the item. According to this type, the item can handle different attributes described in the sections below.
All items have a Top, Left, Width and Height attribute which are used to position the item on the screen. Use the optional connection attribute if you want commands being sent over different connection, not specified in the page configuration.

 
    {
        "type": "button" | "label" | "slider" | "switch" | "webview",
        "top": (int),
        "left": (int),
        "width": (int),
        "height": (int),
        "connection" : (string)
    }

Buttons

Buttons are interactive items that react on the user's input. The shape attribute specifies the button-style (rectangle, rounded, circle).

The sends array defines the strings which will be send through the connection when touching the button. If there are multiple strings defined, the strings will be sent one by one. There is the possibility to define a break between sending commands. For this, just enter a "__wait 1000" command (two underscores). This command will not send anything but wait 1000ms.
If you want the app to send a different command when releasing the button (touch up), define the release attribute.
The repeats command will be repeatedly sent while holding down a button.

If you specify a reads string, the string will be sent after all strings out of the sends array have been sent. The reponse will then be displayed as the buttons label so we are able to display information comming from the device.
The background attribute can be either a color (like textcolor) or a filename of a png file.

 

    {
        "type": "button",
        "top": (int),
        "left": (int),
        "width": (int),
        "height": (int),
        "shape": "rect" | "rounded" | "circle", 
        "icon": "lamp_on" | "lamp_off" | "blue" | "green" | "yellow" | "red" | "down" | "up" | "right" | "left" | "previous" | "reverse" | "play" | "pause" | "stop" | "forward" | "next" | "back" | "standby",
        "label": (string),
        "textcolor" : (string) # r,g,b
        "textalign" : "right" | "center" | "left"
        "sends" : [(string), (string), ...],
        "repeats": [(string), ...], 
        "reads": (string)
        "release" : (string) 
        "connection" : (string)
        "interval" : (int)   # in miliseconds
        "background" : (string) # either r,g,b or *.png
        "border" : (string) # r,g,b
    }

Icons

There are several icons included for rendering a simple remote control for a TV or a DVD Player. If you want to include your own icons, simply add them into the iTunes Filesharing Window or copy them to your SD card in the folder /NetIO/icons (Android) and set the icon accordingly.
For example:

    ...
    "icon" : "mycustomicon.png"
    ...
    

 

This is a list of all available icons:

lamp_on   previous
lamp_off   reverse
green   play
yellow   pause
blue   stop
red   forward
down   next
up   back
right   standby
left

Labels

Labels display text or images. You cannot touch them, but they can read data once or in an interval. Similar to the button, Labels can change their appearance according to the incoming data.

    {
            "type": "label",
            "width": (int),
            "height": (int),
            "top": (int),
            "left": (int),
            "text": (string),
            "textcolor" : "r,g,b", (example: "255,255,255" for white)
            "background" : (string),
            "border" : (string),
            "icon" : (string),
            "textalign" : "right" | "center" | "left"
            "fontsize" : (int), #optional
            "sends" : [(string), (string), ...],  #optional 
            "reads" : (string), #optional
            "interval" : 2000   #optional, in miliseconds
            "connection" : (string) #optional
    }
        

Sliders

Sliders can change a value in a specified range. The slider object needs a minimum and a maximum value. The value is parsed into the sends string which contains '{value}'. This '{value}' string is replaced by the value. If you want your slider to have the correct position on reconnect, specify the reads attribute which excepts a number as response between minvalue and maxvalue (see also Response Handling). The ratio of the slider dimensions is used to render the slider item either vertical or horizontal automatically.

To be more flexible, it is possible to use the CALC keyword in the sends attribute as well. (see Response Handling).

 

{
    "type" : "slider",
    "width": (int),
    "height": (int),
    "top": (int),
    "left": (int),
    "minValue" : (int),
    "maxValue" : (int),
    "showValue" : true | false,
    "textcolor" : (string) # r,g,b 
    "sends" : (string), 
    "reads" : (string), 
    "connection" : (string)
    "interval" : (int)   # in miliseconds
    "highColor" : (string),
    "lowColor" : (string),
    "knobColor" : (string)
}
    

Example: "sends" : "set brightness {value}", "reads" : "get brightness"

Switches

Switches are two-state items which display a specific state and can send different strings depending on their state. To make them work, specify the text which will be displayed for both states (onText, offText), the strings which will be sent depending on the state (onSend, offSend) and the reads attribute, which will set the initial state. The "reads"-response is compared with the onValue to determine the current state. If the state should be updated automatically, specify also an interval.

 

    {
        "type": "switch",
        "width": (int),
        "height": (int),
        "top": (int),
        "left": (int),
        "onValue": (string),
        "offValue" : (string),
        "onText" : (string),
        "offText" : (string),
        "onSend": (string),
        "offSend": (string),
        "reads": (string),
        "interval" : (int)
        "textcolor" : (string),
        "offtextcolor" : (string),
        "knobColor" : (string),
        "onColor" : (string),
        "offColor" : (string),
        "fontsize" : (int)
    },

WebViews

A webview loads the specified url into the given frame. This way, you can easily embed html content like camera images from webcams and ip-cameras or other web control panels! If the 'reloadButton' attribute is set to true, a button will appear which will reload the content. Also, if the url requires basic authentication, you can specify a username and a password (optional), so the webview will login automatically.

    {
        "type": "webview",
        "width": (int),
        "height": (int),
        "top": (int),
        "left": (int),
        "reloadButton": true | false,
        "url": (string),
        "interval" : (int),
        "username" : (string),
        "password" : (string)
    },

Colorpicker

A colorpicker widget can be used to easily select a color. The color value can be send through a connection in different formats: values between 0-255, values between 0-1 or the hex-way #rrggbb. The color values are replaced with {red} {green} and {blue} in the sends or reads commands.

        {
          ...
          "type": "colorpicker",
          "sends": "set {red} {green} {blue}",
          "format": "RGB 0-255",
          "release": "set {red} {green} {blue}",
          "reads": "get color",
          "interval": 2000,
          "comment": "this is a comment",
          "parseResponse": "\\d+",
          "formatResponse": "{0}"
        }

Examples

Format 0-255 and sends "set {red} {green} {blue}" results in "set 255 0 0" for red color.

Format hex and sends "set #{red}{green}{blue}" results in "set #ff0000" for red color.

Text Input

A text input widget can be used to type in a command during runtime. If no "sends" attribute is defined, the whole text of the input field plus the command sendTermination is being sent. If a "sends" is defined, the app replaces {text} with the actual content of the input box. (Default "sends" is only {text}. When reading, the response will replace the content of the input box. This way you are able to predefine texts at runtime.

        {
          ....
          "type": "textinput",
          "buttonColor": "45,45,45",
          "fieldColor": "40,40,40",
          "textColor": "230,230,230",
          "showSendButton": true,
          "textcolor": "255,255,255",
          "sends": "set {text}",
          "interval": 2000,
          "reads": "get value",
          "id": "textinput01"
        }

Response Handling

This feature is very powerful and generic. It consists of two attributes parseResponse and formatResponse which can be defined on all items which read values. If the resulting string starts with an attribute name, you can configure those attributes during runtime.

    {
        ...
        "parseResponse" : (string),
        "formatResponse" : (string),
        ...
    },
    



parseResponse takes a regular expression which parses the response and returns several groups.

formatResponse is a string which takes the matched groups and returns a usable string. Groups are accessible through {number}.
Labels and Buttons will just display the formatted string.
 

Response Process

If data is being received it will be edited by the following components (if defined).
response handling
 

Calculations

Version 2.0 introduced calculations on received responses. If you are using the <calc> tags in the formatResponse attribute, NetIO will dynamically calculate the formula before transfering it to the item. In combination with the matched groups from the parseResponse, you can do small calculations on parts of the response.
 

            # Example Response: 523  (from a microcontroller that send 0-1023 for a temperature showing 0-20 degrees)
            "parseResponse" : "\d+",
            "formatResponse" : "<calc>{0}*0.019</calc> degrees"

            # item will show: 9.937
        

In this example, the <calc> statement will be replaced by the result of the formula containing the first match of the regular expression defined in parseResponse. Define the number of decimal places by adding them as an attribute to the <calc> element. (For example: <calc dec=2> )

We use different calculation libaries in the Android and iOS version. To check what is possible inside <calc> check the possibilities of exp4j for Android and DDMathParser for iOS.

Examples:

Here are a few more examples:

"reads" : "get temperature" #will e.g. return '23.5'
"parseResponse" : "\\d+"    #will determine the numbers in the response
"formatResponse" : "We have {0},{1}°C" #will display "We have 23,5°C" on the label/button
        

 

Sliders and switches will take the formatted string to set their value/state.

 

Slider Example:
"reads" : "get brightness" #will e.g. return 'brightness 44'
"parseResponse" : "\\d+" #will determine the numbers in the response and set the slider to 44
        

 

Switch Example:
"onValue" : "on",
"reads" : "get status" #will e.g. return 'light on'
"parseResponse" : "o[a-z]+" #will get the 'on' in the response and set the switch state to ON after comparing with onValue
        

 

Change Attributes during runtime

It is possible to change the appearance of Buttons and Labels during runtime. According to responses, they can change colors or images. To do so, start with the attribute you want to change followed by the value. This does not work on Sliders and Switches as they use the response data to determine their actual state.
The following attributes can be changed:

  • background (color if three numbers or image if ends with .png)
  • textcolor
  • icon
  • border

 

Change icon of a Button/Label
"sends" : ["toggle lamp"], #will do something
"reads" : "lamp status",   #reads the status and returns e.g. 'lamp_off'
"parseResponse" : ".*$",   #takes the whole response
"formatResponse" : "icon.myicon_{0}.png" #changes the icon to myicon_lamp_off.png from filesharing or sd card

        

 

Change Textcolor of Button:
"reads" : "get led 1",   #reads the status and returns e.g. '255,0,0'
"parseResponse" : ".*$",   #takes the whole response
"formatResponse" : "textcolor.{0}" #changes the textcolor to 255,0,0 which would be red

        

 

 

Learn how to use regular expressions, and test them in regex editors like http://regexpal.com/

Miscellaneous

Comments

Comments like //comment or /* comment */ are not supported in the json file. If you want to add some explanatory information to the file, you could add a "comment" attribute to objects. For example:

 
    {
        ...
        "comment" : "This is a comment to a button",
        ...
    }
 

This has no effect to the UI or functionality, so I suggest not to use it.

 

Sounds / Feedback

 
    {
        ...
        "sounds" : "active" | "inactive" | "keyboardsetting",
        ...
    }
 

There are three values for the sounds setting. "active" simply adds a click sound to every button. "inactive" turns it off and "keyboardsetting" will result in a click sound if you have the keyboard click sounds enabled in your device. Currently, the Android app does not support the sound setting.

Keywords

Switch Page

If a send command or a read command (after formatResponse) is "__page 1" (double underscore), the app will switch to this particular page. With this, you can add buttons that switch to a page directly or switch to a page on specific incoming data.

Wait

Use __wait 1000 (double underscore) to wait 1000ms before sending the next send command. This is available in all send command arrays.

URL Encoding

When using HTTP connections, NetIO can encode your string (for example coming from an input box). Use <encode></encode> in your send command, the content between these tags will be encoded

Calculating

The <calc></calc> tags are used to do calculations on incoming data. Check Response Handling docs for more information