What is watchset?

Watchset is a JSON file with definition of screens and actions available on them. You can define up to 255 screens in one watchset. Every screen contains controls and actions assigned to the events.

Here you can see the simplest watchset that contains only one screen. This screen doesn’t have any controls and handles only one event - closes the watchset when back button is pressed.

 1 {
 2 	"type": "watchset",
 3 	"name": "sample watchset",
 4 	"apiVersion": 1,
 5 	"data": {
 6 		"screens": [
 7 			{
 8 				"id": "sample screen",
 9 				"controls": [
10 				],
11 				"actions": {
12 					"button_back_short": { "action": "close" }
13 				}
14 			}
15 		]
16 	}
17 }

File properties

Every file with watchset definition should contain those parameters:

• type - should be set to “watchset”
• name - user defined name that will show on a list when watchset is imported
• apiVersion - reserved for future use, should be set to “1”
• data - watchset properties

Watchset properties

At this stage watchset data contains only list of screens. In future versions there will be also possibility to define static content (images, fonts) that will be used on the screens. To define multiple screens you have to separate them with a comma.

 1 {
 2 	"type": "watchset",
 3 	"name": "sample watchset",
 4 	"apiVersion": 1,
 5 	"data": {
 6 		"screens": [
 7 			{
 8 				"id": "first screen",
 9 				"controls": [
10 				],
11 				"actions": {
12 					"button_back_short": { "action": "close" }
13 				}
14 			},
15 			{
16 				"id": "second screen",
17 				"controls": [
18 				],
19 				"actions": {
20 					"button_back_short": { "action": "close" }
21 				}
22 			}
23 		]
24 	}
25 }

Screen properties

Every screen should contain:

• id - identifier of the screen (used in places where some event triggers screen change action)
• controls - list of controls that should be shown on this screen
• actions - list of event to action mapping

One screen may contain up to 255 controls and unlimited number of unique actions (but you can assign only one action to one event). Here you can see simple screen that contains two controls (one that shows hour and the second one with minutes). There are three event to action mappings:

• the first one toggles screen colors when the up button is long pressed
• the second one toggles backlight when the back button is long pressed
• the last one close the watchset when the back button is short pressed

 1 {
 2 	"type": "watchset",
 3 	"name": "sample watchset",
 4 	"apiVersion": 1,
 5 	"data": {
 6 		"screens": [
 7 			{
 8 			    "id": "sample watchface",
 9 			    "controls": [
10 			        {
11 			    		"type": "number",
12 			    		"numberRange": "0-99",
13 			    		"position": {
14 			    			"x": 4, 
15 			    			"y": 4
16 			    		},
17 			    		"style": {
18 			    			"type": "generated", 
19 			    			"thickness": 8, 
20 			    			"width": 66, 
21 			    			"height": 76, 
22 			    			"space": 4, 
23 			    			"leftPadded": true
24 			    		},
25 			    		"source": {
26 			    			"type": "internal", 
27 			    			"property": "hour"
28 			    		}
29 			    	},
30 			    	{
31 			    		"type": "number",
32 			    		"numberRange": "0-99",
33 			    		"position": {
34 			    			"x": 4, 
35 			    			"y": 85
36 			    		},
37 			    		"style": {
38 			    			"type": "generated", 
39 			    			"thickness": 6, 
40 			    			"width": 66, 
41 			    			"height": 76, 
42 			    			"space": 4, 
43 			    			"leftPadded": true
44 			    		},
45 			    		"source": {
46 			    			"type": "internal", 
47 			    			"property": "minutes"
48 			    		}
49 			    	}
50 			    ],
51 				"actions": {
52 					"button_up_long": { "action": "toggleColors" },
53 					"button_back_long": { "action": "toggleBacklight" },
54 					"button_back_short": { "action": "close" }
55 				}
56 			}
57 		]
58 	}
59 }

Screen controls

There are few types of controls that can be added to the screen. Every type has it’s own properties.

Number

Number control shows a numeric value. This value can be integer or decimal number. Sample definition of number control looks like this:

 1 {
 2 	"type": "number",
 3 	"numberRange": "0-99",
 4 	"position": {
 5 		"x": 4, 
 6 		"y": 4
 7 	},
 8 	"style": {
 9 		"type": "generated", 
10 		"thickness": 8, 
11 		"width": 66, 
12 		"height": 76, 
13 		"space": 4, 
14 		"leftPadded": true
15 	},
16 	"source": {
17 		"type": "internal", 
18 		"property": "hour"
19 	}
20 }

Number control properties are as follows:

• type - control type, should be set to “number”
• numberRange - number range, possible values are:
  • 0-9
  • 0-19
  • 0-99
  • 0-199
  • 0-999
  • 0-1999
  • 0-9999
  • 0-19999
  • 0-99999
  • 0-9.9
  • 0-19.9
  • 0-99.9
  • 0-199.9
  • 0-999.9
  • 0-1999.9
  • 0-9999.9
  • 0-19999.9
  • 0-99999.9
  • 0-9.99
  • 0-19.99
  • 0-99.99
  • 0-199.99
  • 0-999.99
  • 0-1999.99
  • 0-9999.99
  • 0-19999.99
  • 0-99999.99
• position - x and y coordinates of top left corner of this control
• style - some properties that define how this control should look like, at this stage only generated digits are supported.
  • thickness - digit thickness in pixels
  • width - single digit width
  • height - single digit height
  • space - space in pixels between digits
  • leftPadded - flag that informs if number should be zero padded (1.9 when false or 001.9 when true for 0-999.9 range), this property is skipped for ranges that start with one like 0-199.
• source - data source (check data source section)

Text

Text control renders a text using given font.

 1 {
 2 	"type": "text",
 3 	"position": {
 4 		"x": 1, 
 5 		"y": 10
 6 	},
 7 	"size": {
 8 		"width": 143, 
 9 		"height": 27
10 	},
11 	"font": {
12 		"type": "builtin", 
13 		"name": "normalRegular"
14 	},
15 	"style": {"horizontalAlign": "center"},
16 	"source": {
17 		"type": "extension", 
18 		"extensionId": "com.althink.android.ossw.plugins.sample", 
19 		"property": "stringParam"
20 	}
21 }

Text control properties are as follows:

• type - control type, should be set to “text”
• position - x and y coordinates of top left corner of this control
• size - width and height of this control (text is not rendered outside of this range)
• font - font time, currently only builtin fonts are supported:
  • normalRegular
  • normalBold
  • optionNormal
  • optionBig
• style - text style:
  • horizontalAlign - text horizontal align:
    • left
    • right
    • center
• source - data source (check data source section)

Progress

Progress control renders a horizontal progress bar.

 1 {
 2 	"type": "progress",
 3 	"maxValue": 60,
 4 	"position": {
 5 		"x": 0, 
 6 		"y": 165
 7 	},
 8 	"size": {
 9 		"width": 144, 
10 		"height": 2
11 	},
12 	"style": {"border": 0},
13 	"source": {
14 		"type": "internal", 
15 		"property": "seconds"
16 	}
17 }

Progress control properties are as follows:

• type - control type, should be set to “progress”
• maxValue - maximum value that represents 100% of progress
• position - x and y coordinates of top left corner of this control
• size - width and height of this control
• style - control style:
  • border - renders border of given number of pixels around the progress bar
• source - data source (check data source section)

Data source

Every control definition contains a “source” property that defines what value should be shown. There are three types of data source:

• internal - internal data, available in every mode (peripheral, airplane, central)
• extension - data from an android application extension (only for peripheral mode)
• sensor - data from sensor connected over BLE (only for central mode)

Internal data source

Internal data source is available in every mode. Sample definition looks like this:

{
	"source": {
		"type": "internal", 
		"property": "hour"
	}
}

Extension data source properties are as follows:

• type - should be set to “internal”
• property - internal property name

Available internal properties:

• hour - current hour
• minutes - current minutes
• seconds - current seconds
• dayOfMonth - current day of month
• month - current month
• year - current year
• batteryLevel - current battery level (100 is a max)

Extension data source

Extension data source is available only in peripheral mode. Sample definition looks like this:

{
	"source": {
		"type": "extension", 
		"extensionId": "com.althink.android.ossw.plugins.musicplayer", 
		"property": "artist"
	}
}

Extension data source properties are as follows:

• type - should be set to “extension”
• extensionId - extension identifier
• property - extension property name (for available names check extension documentation)

Sensor data source

Sensor data source is available only in central mode. Sample definition looks like this:

{
	"source": { 
		"type": "sensor", 
		"property": "heartRate" 
	}
}

Sensor data source properties are as follows:

• type - should be set to “sensor”
• property - sensor property name

Available sensor properties:

• heartRate - current heart rate from BLE HR sensor

Event to action mapping

You can assign actions to given events. Sample actions definition looks like this:

1 {
2 "actions": {
3 	"button_up_long": { "action": "toggleColors" },
4 	"button_back_long": { "action": "toggleBacklight" },
5 	"button_back_short": { "action": "close" }
6 }

Available events:

• button_up_short - UP button short pressed
• button_select_short - SELECT button short pressed
• button_down_short - DOWN button short pressed
• button_back_short - BACK button short pressed
• button_up_long - UP button long pressed
• button_select_long - SELECT button long pressed
• button_down_long - DOWN button long pressed
• button_back_long - BACK button long pressed

Available actions:

• toggleBacklight - toggle backlight

{ "action": "toggleBacklight" }

• toggleColors - toggle colors

{ "action": "toggleColors" }

• showScreen - show watchset screen identified by screenId property

{
	"action": "showScreen", 
	"screenId": "second screen"
}

• extensionFunction - invoke function from android application extension, check extension documentation for available functions

{
	"action": "extensionFunction",  
	"extensionId": "com.althink.android.ossw.plugins.musicplayer", 
	"function": "nextTrack"
}

• settings - show settings

{ "action": "settings" }

• close - close a watchset

{ "action": "close" }

Example Watchsets

• heartrate-central.json
• heartrate-peripheral.json
• musicplayer.json
• sampleWatchset.json
• tasker.json

are available on https://github.com/ossw/ossw-firmware-s120/releases