An open source java API for Teletask domotics.
It is the purpose to create an API for software developers or domotics enthusiasts, who are interested in generating their own control environment for the TELETASK domotics systems, so you can create your own user interface and connected solutions and services.
If you own a Teletask MICROS+, you need the (paid) DLL32 LIBRARY (TDS15132).
However, if you're a java programmer like myself, you don't want to use a windows dll :-).
Teletask documentation on how their API works can be found here: https://teletask.be/media/3109/tds15132-library.pdf
The program supports the MICROS+ (maybe also NANOS/PICOS, but untested), but you'll have to buy a licence to be able to make TCP calls.
You can find the latest docker images at: https://hub.docker.com/r/ridiekel/jeletask2mqtt
Create a configuration json file following this example. At this time I can only test with MICROS_PLUS. Please log an issue when you are having trouble with the other types of central unit. If teletask has not changed their binary API, it should be compatible.
The type
Can be either PICOS
, NANOS
, MICROS_PLUS
{
"type": "MICROS_PLUS",
"componentsTypes": {
"RELAY": [
{
"number": 1,
"description": "Power outlet",
"type": "switch"
},
{
"number": 23,
"description": "Living Room - Closet lights"
},
{
"number": 36,
"description": "Living room - ceiling lights"
}
],
"SENSOR": [
{
"number": 1,
"description": "Light Sensor",
"type": "LIGHT"
},
{
"number": 2,
"description": "General Analog Sensor 1",
"type": "GAS",
"gas_type": "4-20ma",
"gas_min": 0,
"gas_max": 14,
"decimals": 2
},
{
"number": 3,
"description": "Temperature Sensor",
"type": "TEMPERATURE",
"ha_unit_of_measurement": "°C"
},
{
"number": 4,
"description": "HVAC / AC",
"type": "TEMPERATURECONTROL"
},
{
"number": 5,
"description": "Aurus wall switch in the attic",
"type": "TEMPERATURECONTROL"
},
{
"number": 6,
"description": "Pulse counter energy Airco",
"type": "PULSECOUNTER"
}
],
"COND": [
{
"number": 1,
"description": "Condition Example"
}
],
"FLAG": [
{
"number": 6,
"description": "Flag Example"
}
],
"GENMOOD": [
{
"number": 1,
"description": "All off"
}
],
"MOTOR": [
{
"number": 1,
"description": "Blinds"
}
],
"LOCMOOD": [
{
"number": 1,
"description": "Watch TV"
}
],
"TIMEDMOOD": [
{
"number": 1,
"description": "Outdoor light"
}
],
"DIMMER": [
{
"number": 1,
"description": "Spots"
}
],
"INPUT": [
{
"number": 42,
"description": "State of TDS12117 input nr 3",
"long_press_duration_millis" : 2000
}
],
"TIMEDFNC": [
{
"number": 3,
"description": "Timed function nr 3 (pulse for garage door)"
}
],
"DISPLAYMESSAGE": [
{
"number": 1000,
"bus_numbers": "1,1",
"address_numbers": "13,5",
"description": "Aurus living room + aurus basement"
}
]
}
}
Variable | Type | Default value | Description |
---|---|---|---|
TELETASK_HOST | Required | The ip address or hostname of your central unit | |
TELETASK_PORT | Required | The port of your central unit, probably 55957 | |
TELETASK_ID | Required | The id used in mqtt messages of the central unit | |
TELETASK_MQTT_HOST | Required | The host of your MQTT broker | |
TELETASK_MQTT_PORT | Optional | 1883 | The port of your MQTT broker |
TELETASK_MQTT_USERNAME | Optional | The MQTT broker username | |
TELETASK_MQTT_PASSWORD | Optional | The MQTT broker password | |
TELETASK_MQTT_CLIENTID | Optional | teletask2mqtt | The client id used for connecting to MQTT |
TELETASK_MQTT_PREFIX | Optional | teletask2mqtt | The MQTT message topic prefix |
TELETASK_MQTT_RETAINED | Optional | false | Indicates whether or not the messages should be retained by the broker |
TELETASK_MQTT_DISCOVERY_PREFIX | Optional | homeassistant | The MQTT home assistant discovery prefix |
TELETASK_PUBLISH_MOTOR_POSITION | Optional | true | Publish the position of the motor |
TELETASK_PUBLISH_MOTOR_POSITION_INTERVAL | Optional | 250 | How frequently the position is published when the motor is running (in milliseconds). |
TELETASK_PUBLISH_STATES_INTERVAL | Optional | 300 | How frequently the states are force refreshed (in seconds). A negative value disables the force refresh of states. |
TELETASK_LOG_HACONFIG_ENABLED | Optional | false | (Advanced) Log the homeassistant config messages |
TELETASK_LOG_TOPIC_ENABLED | Optional | false | (Advanced) Add the topic name to the log message |
LOGGING_LEVEL_IO_GITHUB_RIDIEKEL_JELETASK_MQTT | Optional | INFO | (Advanced) log level of messages going from/to teletask central unit. Can be ERROR (least log messages), WARN, INFO, DEBUG or TRACE (extensive log messages) |
LOGGING_LEVEL_IO_GITHUB_RIDIEKEL_JELETASK_CLIENT | Optional | INFO | (Advanced) log level of messages going from/to mqtt. Can be ERROR (least log messages), WARN, INFO, DEBUG or TRACE (extensive log messages) |
Different versions (tags) are provided. Depending on your needs, you will need a different version (tag)
Tag | Description |
---|---|
latest-amd64 | The latest version of the application. Built for amd64 arhitecture. |
latest-arm64 | The latest version of the application. Built for arm64 architecture llike raspberry pi 4. |
latest-native | The latest version, but built with spring boot native. This is only available for amd64, but should boot a lot faster on that architecture. |
You should be able to run using following minimal command:
docker run --name jeletask2mqtt \
-v "<path_to_your_confg_json>:/teletask2mqtt/config.json" \
-e TELETASK_HOST="<teletask_ip_address>" \
-e TELETASK_PORT="<teletask_port>" \
-e TELETASK_ID="<teletask_id>" \
-e TELETASK_MQTT_HOST="<mqtt_host>" \
ridiekel/jeletask2mqtt:latest
version: '3.8'
services:
mqtt:
image: eclipse-mosquitto
restart: unless-stopped
volumes:
- $HOME/.jeletask/mosquitto/data:/mosquitto/data
- $HOME/.jeletask/mosquitto/logs:/mosquitto/logs
ports:
- "1883:1883"
networks:
- jeletask
command: "mosquitto -c /mosquitto-no-auth.conf" #Needed for unauthenticated mqtt broker with listen address 0.0.0.0
jeletask2mqtt:
image: ridiekel/jeletask2mqtt:latest-native
restart: unless-stopped
volumes:
- $HOME/.jeletask/teletask2mqtt/config.json:/teletask2mqtt/config.json
environment:
TELETASK_HOST: 192.168.0.123
TELETASK_PORT: 55957
TELETASK_ID: my_teletask
TELETASK_MQTT_HOST: mqtt
depends_on:
- mqtt
networks:
- jeletask
networks:
jeletask:
When using mosquitto clients you should be able to easily test your config.
In ubuntu you can use:
sudo apt install -y mosquitto-clients
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/relay/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/relay/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/relay/1/set \
-m '{"state":"OFF"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/locmood/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/locmood/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/locmood/1/set \
-m '{"state":"OFF"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/genmood/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/genmood/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/genmood/1/set \
-m '{"state":"OFF"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedmood/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedmood/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedmood/1/set \
-m '{"state":"OFF"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/state
For turning on you can use ON
(goes to 100%), OFF
(goes to 0%), PREVIOUS_STATE
(goes to last %) or any integer value between 0
and 100
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"state":"ON"}'
or
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"state":"75"}'
or
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"state":"ON", "brightness": "60"}'
For turning off, you can use either OFF
or 0
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"state":"OFF"}'
or
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"state":"0"}'
or
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/dimmer/1/set \
-m '{"brightness":"0"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/motor/1/state
The following json attributes are provided on the /state MQTT topic:
Attribute | Possible Values | Description |
---|---|---|
state | ON OFF |
Running Not running |
last_direction | UP/DOWN | Last running direction |
protection | 0 1 2 3 4 |
No protection defined On, and the motor is controlled by the protection On, but the motor is not controlled by the protection On, but overruled by user protection switched OFF |
position | 0 - 100 | If state is ON, the position we're running to |
current_position | 0 - 100 | The current position |
seconds_to_finish | Time, in seconds, it'll take to get to position |
You can send either UP
, DOWN
or STOP
to the motor function.
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/motor/1/set \
-m '{"state":"UP"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/motor/1/set \
-m '{"state":"STOP"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/motor/1/set \
-m '{"state":"DOWN"}'
You can also send the motor to a position.
Position can be anything between 0
and 100
.
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/motor/1/set \
-m '{"position": 25}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/flag/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/flag/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/flag/1/set \
-m '{"state":"OFF"}'
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/sensor/1/state
The following sensor types are currently supported:
Type | Description |
---|---|
TEMPERATURE | Teletask temperature sensor (TDS12250, TDS12251). Value is in °C. |
TEMPERATURECONTROL | Teletask temperature controllabe sensor (Aurus OLED, HVAC, ...) |
HUMIDITY | Teletask humidity sensor (TDS12260). Value is in %. |
LIGHT | Teletask light sensor (TDS12270). Value is in Lux. |
GAS | Teletask General Analog Sensor. |
PULSECOUNTER | Teletask pulse counter (returns current reading + total). |
The following additional Home Assistant related parameters are available:
Config parameter | Description |
---|---|
ha_unit_of_measurement | To specify a custom 'unit_of_measurement' in HA auto discovery. For example: "°C" |
ha_modes | To specify a custom "modes" in HA auto discovery. Default: "auto,off,cool,heat,dry,fan_only" |
hatype | We try to guess the type of the component based on the type in teletask, but sometimes you will want to override this. You can use hatype for this |
This type of sensor has 3 additional config parameters:
Config parameter | Description |
---|---|
gas_type | One of the 4 possible signal options: "4-20ma", "0-20ma", "0-10V" or "5-10V" |
gas_min | The "Min" value (see PROSOFT configuration) |
gas_max | The "Max" value (see PROSOFT configuration) |
decimals | How many decimals you want returned (rounded up) |
Use TEMPERATURECONTROL for any temperature controllable 'sensor' like an AC (HVAC) or an Aurus OLED wall switch
The following json attributes are provided on the /state MQTT topic:
Attribute | Possible Values | Description |
---|---|---|
state | ON/OFF | |
current_temperature | The current temperature | |
target_temperature | The set target temperature | |
decimals | How many decimals you want returned (rounded up) | |
preset | DAY/NIGHT/ECO | The current preset |
mode | AUTO/HEAT/COOL/VENT/DRY | The current mode |
fanspeed | SPAUTO/SPLOW/SPMED/SPHIGH | The current fan speed |
window_open | 0 = closed / 255 = open | Window state (Untested) |
swing_direction | switch direction as value (Untested) | |
output_state | Untested/Unsure | |
day_preset_temperature | Day preset temperature (see prosoft) | |
night_at_heating_preset_temperature | Night at heating temperature (see prosoft) | |
night_at_cooling_preset_temperature | Night at cooling temperature (see prosoft) | |
eco_preset_offset | ECO offset preset temperature (see prosoft) |
The following "state" attribute commands are supported on the /set MQTT topic:
For state change | Description |
---|---|
ON | Turn on the device |
OFF | Turn off the device |
ONOFF | Toggle on or off the device |
UP | Set target temperature up 0.5°C |
DOWN | Set target temperature down 0.5°C |
For preset change | Description |
---|---|
DAY | Change to day preset |
NIGHT | Change to night preset |
ECO | Change to eco preset |
For operation mode change | Description |
---|---|
AUTO | Set operating mode to auto |
HEAT | Set operating mode to heat |
COOL | Set operating mode to cool |
VENT | Set operating mode to vent |
DRY | Set operating mode to dry |
MODE | Toggle between available modes |
For fan speed change | Description |
---|---|
SPAUTO | Set fan speed to auto |
SPLOW | Set fan speed to slow |
SPMED | Set fan speed to medium |
SPHIGH | Set fan speed to high |
SPEED | Toggle between available modes |
You can also set the target temperature by sending the desired temperature to the "target_temperature" attribute.
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/input/1/state
The following json attributes are provided on the /state MQTT topic:
Attribute | Possible Values | Description |
---|---|---|
state | OPEN CLOSED NOT_PRESSED LONG_PRESS SHORT_PRESS |
Button is being pressed Button press finished Button is not being pressed Button was pressed for a long time (configurable) Button was pressed for a short time (configurable) |
open_time | long | The time the pressing started (when state is LONG_PRESS or SHORT_PRESS) |
close_time | long | The time the pressing ended (when state is LONG_PRESS or SHORT_PRESS) |
long_press_config_in_millis | integer | The configured amount of time for long press to occur |
press_duration_millis | integer | The actual amount of time the button was pressed (when state is LONG_PRESS or SHORT_PRESS) |
mosquitto_sub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedfnc/1/state
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedfnc/1/set \
-m '{"state":"ON"}'
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/timedfnc/1/set \
-m '{"state":"OFF"}'
You can only send a display message. Listening for events is not supported.
DISPLAYMESSAGE config attribute parameters:
Attribute | Description |
---|---|
number | A unique DISPLAYMESSAGE number |
bus_numbers | A list of BUS numbers (see below) |
address_numbers | A list of ADDRESS numbers (see below) |
description | Description for this config entry |
bus_numbers
and addres_numbers
are two comma separated lists of the same size.
They contain the Teletask bus number(s) and Teletask interface address(es) of the interface(s) on which to display the Message/Alarm
mosquitto_pub -h <TELETASK_MQTT_HOST> -p <TELETASK_MQTT_PORT> \
-t <TELETASK_MQTT_PREFIX>/<TELETASK_ID>/displaymessage/1000/set \
-m '{"message_line1":"DOORBELL","message_line2":"PLEASE OPEN!", "message_beeps":"10","message_type="message"}'
Notes:
- Both lines each have maximum length of 16 chars. This is a Teletask limitation.
- message_type can either be "alarm" or "message".
Auto configuration should work with relays, dimmers, motors, sensors, timed functions, flags, general/local/timed moods, conditions and digital inputs. Other types are not yet supported, work in progress. Pleas log an issue when having trouble with auto configuration in HA.
The bridge creates 1 device with id teletask-<TELETASK_ID>
, and adds entities with the following entity id pattern: light.teletask_<TELETASK_ID>_<FUNCTION_TYPE>_<COMPONENT_NUMBER>
, which should be unique for your installation.
Examples:
switch.teletask_my_teletask_relay_1
light.teletask_my_teletask_relay_36
The default type of relay is light
, but can be overridden.
Possible values: https://www.home-assistant.io/docs/mqtt/discovery/#lighting
"RELAY": [
{
"number": 1,
"description": "Power outlet",
"type": "switch"
},
{
"number": 23,
"description": "Living Room - Closet lights"
},
{
"number": 36,
"description": "Living room - ceiling lights"
}
]
The config message is published to topic: <TELETASK_MQTT_DISCOVERY_PREFIX>/<HA_COMPONENT_TYPE>/<TELETASK_ID>/<FUNCTION_TYPE>_<COMPONENT_NUMBER>/config
{
"device": {
"identifiers": [
"<TELETASK_ID>"
],
"manufacturer": "teletask",
"name": "teletask-<TELETASK_ID>",
"model": "<Your model type>"
},
"~": "<TELETASK_MQTT_PREFIX>/<TELETASK_ID>/relay/1",
"state_topic": "~/state",
"unique_id": "<TELETASK_ID>-<FUNCTION_TYPE>-<COMPONENT_NUMBER>",
"name": "<COMPONENT_DESCRIPTION>",
"command_topic": "~/set"
}
Topic: homeassistant/light/my_teletask/relay_36/config
{
"device": {
"identifiers": [
"my_teletask"
],
"manufacturer": "teletask",
"name": "teletask-my_teletask",
"model": "Micros Plus"
},
"~": "teletask2mqtt/my_teletask/relay/1",
"state_topic": "~/state",
"unique_id": "my_teletask-relay-36",
"name": "Living room - ceiling lights",
"command_topic": "~/set"
}