The Touch Switch application uses configuration files from the switch creator found on the zencontrol cloud. 

The switch creator provides options to create a basic single screen with a number of buttons which can send commands via TPI. The final step of the switch creator provides the generated json code. You can modify this screen to provide much greater functionality to Touch Switch installations. 

Touch Switch can provide any number of screens with different configurations. Each must be defined in the controllers list defined in the app_data.json file, The first object found in this list will be the main screen shown when the application is opened, if the final controller has the controller_id “lock_controller” the application will show this controller after some timeout. 

For specfic information about each element see How is the Touch switch JSON structured. 

Controllers 

GridControllerData

String controller_id;  GridControllerDataVariant portrait;   GridControllerDataVariant landscape;    ButtonType layout_click_type;  //layout click data  CommandData command_data;  ArrayList<MultipleButtonData> sub_buttons;  SubButtonPopupData sub_button_layout_info;  String destination_controller_id;  //init command data  Boolean send_command_on_init;  CommandData layout_init_command;  Integer footer_logo_width_pixels;  //for querying information from the control system on a timer  ArrayList<Event> events;

 

A controller must be defined with a controller_id which is a string which is used to gain access to the controller from VIEW_TRANSACTION buttons, and one of landscape or portrait variants  depending on which orientation you would like the device to be oriented in, if you would like to be able to rotate the android device while using the application, you must define both orientations. 

A controller can define a layout_click_type which gives the ability to do the following things: 

BUTTON_TYPE	Action
NON_CLICKABLE	No action occurs when layout is clicked (this is the default if not defined)
COMMAND	when layout is pressed TPI command will be send (command_data must be defined)
SUB_BUTTON	A sub button layout will be shown when the layout is clicked, options for sub buttons must be defined in sub_buttons and sub_button_layout_info now mandatory
VIEW_TRANSACTION	Change to a different controller using the destination_controller_id (must match controller_id of one of the defined controllers)
DISMISS_VIEW	Controller will close when pressed (useful to create lock screens)

 

GridControllerDataVariant 

GridControllerDataVariant

ArrayList<GridButtonData> buttons;  Integer row_count;  Integer column_count;  Boolean plan_mode; //will have plan view background  Boolean sub_button_footer;  String background_file_name;  Integer background_colour;

Each orientation of the controller is defined in a variant, either portrait or landscape, each variant defines a grid which buttons will be placed on to be displayed. Each variant must contain a list of buttons which will be shown in that view, and the row_count and column_count of the grid.  

There are several optional elements plan_mode is a boolean switch which tells the application to display the file defined in background_file_name (to add pictures to your site you must send a support request). You can also force all footers to show at the bottom of the page using sub_button_footer. The background_colour for each view can also be defined as a signed integer representation of the hex string in the format “AARRGGBB” where A is alpha, R is red, G is green, and B is blue. 

 GridButtonData 

GridButtonData

CommandData command_data;  String label;  GridButtonProperties properties;  ArrayList<State> states;  ButtonType type;  AltCommandMode alt_mode; CommandData init_command_data;  ArrayList<MultipleButtonData> sub_buttons;  SubButtonPopupData sub_button_layout;  String destination_controller_id;  Integer slider_max;  Integer slider_min;  RGBWAFData rgbwaf_data;

Each button defined in a variant list must contain properties, a GridButtonProperties object defined below as well as a type the options for which are defined below. 

There are several optional elements which can be defined: 

If using one of the button types which sends a TPI command (COMMAND, SLIDER, STATE_BUTTON, IMAGE_COMMAND, DIMMER_COMMAND, or IMAGE_DIMMER_COMMAND, STATE_BUTTON, STATE_BUTTON_TOGGLE) you must define the CommandData object named command_data. 

The user displayed string should be defined in label. 

When using a VIEW_TRANSACTION type button set a destination_controller_id which matches the id of one of the controllers in the main list. 

When using a STATE_BUTTON_TOGGLE you must define an alternate command to be run when the toggle is not illuminated, this should be done using init_command_data. 

When using a dimmer button it is possible to use an alternate command which will run depending on the alt_mode setting . This is useful for creating STEP_UP or STEP_DOWN dimmers which should use the init_command_data to send STEP_UP_AND_ON or STEP_DOWN_AND_OFF. This can be created using the switch creator. 

AltCommandMode	Action
BOTH	init command will run when the user presses and releases a button
START	init command will run when the button is first pressed
END	init command will run when button is released

To create a button with multiple options you can set the type to SUB_BUTTON or SUB_BUTTON_DIMMER this allows for a 2,3 or 4 button layout to appear wherever you would like, you could use this to have the layout appear near the button which launched it or in a space left in your layout. 

To create a slider define a button as normal, then set the type to SLIDER, then define the slider_max and slider_min to define the limits of the slider. 

RGBWAFData

This object defines the UI for  COLOUR_RGBWAF_COMMAND button type.

RGBWAFData

RGBWAFChannel channel_0; RGBWAFChannel channel_1; RGBWAFChannel channel_2; RGBWAFChannel channel_3; RGBWAFChannel channel_4; RGBWAFChannel channel_5;

 

RGBWAFChannel

boolean channel_enabled; RGBWAFAssignedColour channel_colour; String channel_label; Integer slider_max; Integer slider_min;

 

RGBWAFAssignedColour

RED, GREEN, BLUE, WHITE, AMBER, FREECOLOUR;

 Any RGBWAFChannel can be null, if this is the case it will not be shown. If defined it will show a slider which has the limits defined in slider_min and slider_max.

MultipleButtonData 

When using a SUB_BUTTON you should define a list of MultipleButtonData objects 

MultipleButtonData

CommandData command_data;  CommandData init_command_data;  String label;  ButtonViewParameters view_parameters;

These elements are the same as those used in GridButtonData 

SubButtonPopupData 

This object contains the styling information for the sub button layout.  

SubButtonPopupData

String label;  int label_text_colour;  float label_text_size;  int popup_width;  int popup_height;  int start_x;  int start_y;

label_text_colour is a signed integer representation of the hex value #AARRGGBB. start_x and start_y are the row and column start positions of the popup in pixels. popup_width and popup_height define the size of the popup in pixels. 

GridButtonProperties 

GridButtonProperties

Integer column_size;  Integer column_start;  Integer row_size;  Integer row_start;  ButtonViewParameters view_parameters;

 

Each element of the GridButtonProperties is mandatory. 

column_start and row_start define the starting position of the button in the grid defined in GridControllerDataVariant row_count and column_count where the top left corner is (0,0). 

column_size and row_size are the span in each dimension. Ensure that the start and size element in both dimensions don’t exceed the counts defined in GridControllerDataVariant. 

You must also define ButtonViewParameters which contains the information about various view parameters for each button. 

ButtonViewParameters 

ButtonViewParameters

Float alpha;  int button_colour;  String button_colour_hex;  int button_pressed_colour;  String button_pressed_colour_hex;  String image_path;  boolean skeleton_mode;  int text_colour;  String text_colour_hex;  int text_pressed_colour;  String text_pressed_colour_hex;  float text_size;  boolean tint_image;  Integer text_gravity; int button_state_unknown_colour; String button_state_unknown_colour_hex;

For every button the following must be defined, button_colour, button_pressed_colour, text_colour, text_pressed_colour, and text_size. All colour values (button_colour, button_pressed_colour, text_colour, text_pressed_colour, button_state_unknown_colour are a signed integer representation of the hex value #AARRGGBB). 

All colour values (button_colour_hex, button_pressed_colour_hex, text_colour_hex, text_pressed_colour_hex, button_state_unknown_colour_hex are a Strings which contain the hex value "#AARRGGBB"). 

colour_hex values override colour values. one of colour or colour_hex must be defined.

 

alpha is a decimal value between 0 and 1 where 0 is invisible and 1 is visible. 

image_path should be the file name stored in the assets folder. 

gravity see android reference https://developer.android.com/reference/android/view/Gravity 

button_state_unknown_colour is the default colour for the state indicator  

tint_image if set image from image_path will match text_colour and text_pressed_colour 

CommandData 

CommandData

String ip;  byte control;  byte data_0;  byte data_1;  byte data_2;  byte address;  byte command;  int port;

This object defines the TPI commands. For more information regarding TPI see the TPI document: https://support.zencontrol.com/hc/en-us/articles/360000337175 

 

ButtonType 

BUTTON_TYPE	Action
COMMAND	Send TPI command when pressed.
SUB_BUTTON	Show sub button layout when pressed.
VIEW_TRANSACTION	Go to different page when pressed.
NON_CLICKABLE	Pressing performs no action, useful for text labels.
IMAGE	Same as NON_CLICKABLE, display image.
DISMISS_VIEW	Pressing closes current view, shows previous page.
SUB_BUTTON_DIMMER	Shows sub button layout with dimmer when pressed.
SLIDER	Display slider, useful for changing arc levels or creating DT6 colour changing.
STATE_BUTTON	Send TPI command when pressed, show status of event query.
STATE_VIEW	Pressing performs not action, shows status of event query.
IMAGE_COMMAND	Same as DIMMER, displays image rather than text.
DIMMER_COMMAND	Holding button send command repeatedly, optional repeat command can also be defined.
IMAGE_DIMMER_COMMAND	Same as DIMMER_COMMAND shows image rather than text.
STATE_BUTTON_TOGGLE	Sends TPI when pressed, shows status of event query, change command sent depending on status.

 

State 

State

Action action;  Condition condition;  String event_label;

If using a button type which can display state (STATE_BUTTON, STATE_VIEW, STATE_BUTTON_TOGGLE) you must define it here. Each button can contain any number of states, each element of the state object must be defined. 

Action 

Action

int status_colour;  ActionType type;

 

This is the action which will be performed when the Condition for the state is met. When the action type is set to view the status_colour must be defined  

Condition 

Condition

Answer answer;  ConditionType type;

The condition defines the expected answer from the event which matches the event_label. 

Answer 

Answer

byte answer_byte;  AnswerType type;

See the TPI document for expected answers for query.