Table of Contents

1. Top of Page

2. Introduction

2.1 Specifications

2.2 Menu Structure

3. Configure

3.1 Set Name

3.2 Radio Settings

3.2.1 Requirements

3.2.2 Per-Digit Setting

3.2.3 Value Setting

3.3 IO HDW Setting

3.4 Adding Devices

3.5 Device Control

3.6 Add Tode (Remote)

3.7 Deleting

3.7.1 Deleting Devices

3.7.2 Deleting Remote Todes

3.7.3 Factory Reset

4. IO Devices

4.1 Common Settings

4.2 OnOff

4.3 AnaInput

4.4 AnaOutput

4.5 Distance

4.6 STSTP3W

5. Automation (Logic)

5.1 SetPoint

5.2 Math

6. System

7. MQTT Control

7.1 Tode Setup

7.2 OpenHab Server Setup

7.2.1 Openhabian

7.2.2 Putty

7.2.3 MQTT Broker & Client

7.2.4 Serial2MQTT

7.2.5 OpenHab

A. MQTT /get Value Update

Tode-RC

Users Guide

Setup and Operation



http://www.TGit-Tech.com

Firmware Version: 232H

Last Updated: 2023-02-22







1.Contents





2.Introduction




The Tode System is licensed under the MIT License.

It's hosted on Github.com at: https://github.com/TGit-Tech/Tode-RC


2.1Specifications


2.2Menu Structure




Power-On 1st Screen

This-Todes

Tode-Screen

Press Right on

This-Todes

Tode-Screen

Goes to 2nd,3rd, etc.... Remote

Tode-Screens

On Initial Power-ON nothing changes because there are NO other Remote Todes added at this Time.

Press on

This-Todes

Tode-Screen

Goes to This-Todes

Setup-Screen





3.Configure

3.1Set Name

  1. Enter a Name for This-Tode

On SETUP Screen

SETUP, 'Set Name'

SETUP,'Set Name'

Press to the blank [NAME] field.

Press

On 'Set Name' Screen

Press

Text Entry Field highlights (Blue)







Text Entry Field is Red when not selected else Blue when Selected by .

Once Selected (BLUE) Character Position (WHITE) can be Selected by

SETUP

'Set Name'

Entering a Name

SETUP

'Set Name'

Saving & Exiting

SETUP







To Edit or Clear a Character Position; Highlight the Text Field (BLUE) and select the character to replace (WHITE) then choose the replacement character press SET. The BLANK character is directly under the “EXIT”.

3.2Radio Settings

3.2.1Requirements

SecNet

(Range 01-7F)

Security Code selected by you that prevents unauthorized access to your Tode network.

Frequency

(410 to 441)MHz

The radio frequency (channel) for Tode Communication.


Address

(Range 0000-FFFE)

A radio address to identify each Tode uniquely decided upon by you.


Tx Power

(21,24,27,30)dBm

Sets the (Tx) Transmitting Power of the Radio.

Lower saves power, Higher transmits farther.

PC Connex

(On -or- Off)

When set to On it ties the radio terminal to the USB Port.

This a special function generally ignored by users.

3.2.2Per-Digit Setting

  1. Choose any SecNet Value between 01 to 7F and Set that Value.

SETUP

SETUP

RADIO

SETUP

RADIO (Per-Digit Set)

to select Radio.

Press

to select SecNet

to select Value

Press to change.

Press again to set.







SecNet and Address use Per-Digit Set where each digit is changed at a time.

The WHITE background indicates the selected digit. Use to change the selected digit and to change the digits value. Going beyond the number of select-able digits will exit setting without saving changes.


  1. Choose any *Unique* Address Value for this Tode between 0001 and FFFE and set that Value the same way Per-Digit Set as done to set SecNet.

3.2.3Value Setting

  1. Choose any Frequency between 410MHz and 441MHz (default is 433MHz).


SETUP

RADIO

SETUP

RADIO

SETUP

RADIO (Value Set)

to Frequency

to select Value

Press to change.







to Increment Value

to Decrement Value

Press to save Value.

to Frequency

again to SETUP







  1. Choose the lowest Tx Power level that will sustain communications.


3.3IO HDW Setting


  1. A Tode that has connected devices must know what IO HDW is used to connect the devices. If the Tode will be used only as a hand-held control device, then setting the IO HDW is not needed.

    1. At the time of this writing the only option for connecting devices is a SideIO Plug (SIOST stands for SideIO with Screw Terminals).


SETUP

SETUP

SETUP

to IO HDW

to select Value

(I.e. 'NotSet' in picture)


then or

select SideIO

to set the value








  1. NOTICE: If the IO HDW has not been set before trying to set a device PIN the Tode will notify you with SetHDW as shown below.



3.4Adding Devices


See 5.1 Section for more information on Device Support and Setup.


SETUP

SETUP

Add Device

This-Tode

or

select Add Device

Press

or

Select Device to Add.

Press

The added device appears as ?NAME?

0 is the Device Index #







This-Tode

Select Device

Selected Device

=Device Set Name

Selected Device

=Device Setup

select 0?NAME?

Press enter Set Name

for the Device.

Same routine as setting a Tode name.

Re-Select Device.

Press enter Setup

Enter Device specific Setup Settings (Ex. Only)





N
ote: OLoOff

Output Low, when Off

3.5Device Control


Below shows an example of how to change an Output Device’s State.


This can be done on LOCAL (This-Tode) devices or devices on Remote Todes.

To add a Remote Tode see 3.6.Add Tode (Remote)


NOTE: Remote Tode Devices will show a value of ‘?’ until the readings are requesting by pressing .


This-Tode

This-Tode

This-Tode

select RELAY1

to select Value Value 'Off'

Press

to set a new value.

change Value

to set the value


Once set to 'On'

Relay1 on pin 33 should activate.








3.6Add Tode (Remote)

RC2 Radio Settings

Required

RC1 Radio Settings




SecNet has to Match.


Address must be different / unique.


Frequency has to Match.




On Tode RC2


add RC1 by Address

Check for an RC1 “remote” Tode Screen.

select Add Tode

to select Value

to set RC1-Address

Again to load RC1

RC1 remote Screen







Now the Devices on RC1 can be controlled by RC2.

If the “remote” Tode RC1 failed to show up; try again closer to the unit.

3.7Deleting


3.7.1Deleting Devices

To Delete a Device enter the Device Setup Screen as shown in 3.4.Adding Devices and select Del Device and press .


3.7.2Deleting Remote Todes

To Delete a Remote Tode control screen. Select Del Tode on the SETUP menu and then select the Remote Tode by Name on the list and press .


3.7.3Factory Reset

Preforming a factory reset deletes the Tode Name and all Devices and Remote Todes. Radio Setting are preserved. To preform this operation…


select Reset????


Note: The 4-Digit after Reset is the Firmware Version Loaded.


Firmware 231D

to select Value

to set

to set Yes

again to apply.

The Tode will automatically Reboot and the blank Tode screen will show.












4.IO Devices


4.1Common Settings

4.2OnOff




On Off Device Setup Screen

Pin

Can be any Pin Selectable

pinMode

See pinMode options in #4.1.Common Settings

Del Device

Select and to delete this device.











4.3AnaInput


The equation for Value = (Pin-Reading + PreAdd) * (MultNum/MultDen) + Add.

MultDen cannot be 0 so 0 equivocates to 10K (10,000)



On Off Device Setup Screen

Pin

The Pin to read from (must be an ‘A’ pin)

pinMode


PreAdd

1st Add this amount to the Pin reading.

MultNum

2nd Multiply by fraction (Fraction Numerator)

MultDen

(Fraction Denominator)

Add

3rd Add after fraction multiply (i.e. offset value)

Samples

Number of reading to gather and average for value.




4.4AnaOutput




AnaOutput is the PWM output operation

Pin

Analog Output is Always on PIN #45
















4.5Distance


This is used for Sonic Distance Sensors with a Trigger & Echo Pins.




Distance Device Setup Screen

Trig

The Trigger Pin




The Trigger Pins pinMode

Echo


The Echo Pin

EchoPMode

Echo Pins pinMode

Samples

Number of Samples to Average for Value









4.6STSTP3W


This is used for panels with a START and STOP momentary push buttons.




3-Wire On/Off Momentary (3-second) Switch

StartPin

OUTPUT hat triggers to initiate a START button.

StartPMode

StartPin pinMode Setting

StopPin

The Pin that triggers to initiate a STOP button.

StopPMode

StopPin pinMode Setting

Status

INPUT; Pin that determines current state.

StatPMode

Status Pins pinMode

Del Device

Select and to delete this device.




5.Automation (Logic)

5.1SetPoint


Compares an Input Device reading to a User SetPoint and if the Input reading is outside the boundaries (+/- Tolerance) then it sets an Output Device respectively.


For example; A tank of water with a level sensor can maintain it’s water level by switching ON or OFF a pump that feeds the tank.




On Off Device Setup Screen

InputDev

The Device Index to read a value from

InTolernc

The (+/-) tolerance allowed from setpoint

OutTode

The Tode Index of Out Device (optional) or 0-local

OutDev

The Device Index to SET the value on (optional)

LOutSet

SET value on OutDev when Input is < setpoint


HOutSet

SET value on OutDev when Input is > setpoint


SET value can be ON or OFF


Or INCR/DECR where Difference between setpoint


5.2Math


Implements Mathematical Operation on TWO input readings and (Optionally) sends the computed value to an output device if the value breaks tolerance (+/-) boundaries (i.e. Value changes significantly).




On Off Device Setup Screen

In1Dev

The Device Index to read a value from

Operator

(+)(-)(x)(/) plus, minus, times, divide or AVE-average

In2Dev

The Device Index to read a value from

Tolerenc

+/- Change Tolerance before setting Output

OutTode

The Tode Index of Out Device (optional) or 0-local

OutDev

The Device Index to SET the value on (optional)






Note: When OutTode is a Remote Tode; values are only sent every 14s when the In-Value passes +/- Tolerance of the last sent value.




















6.System


The System menu allows one to do factory resets, enable MQTT, Soft Reset the unit and lookup the firmware version loaded. Pressing the Okay button on the FWver-???? entry causes the Soft Reset.




System Sub-menu

USBSerial

What the Top USB plug is used for (auto-reboots)


Factry RST

Factory Reset

Pub ADiscv

Publish homie MQTT data for Auto-Discovery

SRFWv-????

Soft Reset. Displays current Firmware verson.
















7.MQTT Control


Tode-RC firmware ver.232D+ has support for ‘homieMQTT’ Internet of Things(IoT) control using the Serial plug to connect a Tode to a Raspberry Pi IoT server.


7.1Tode Setup


In SETUP→System→USBSerial set to ‘MQTT’.

See 6.System for details.





7.2OpenHab Server Setup


7.2.1Openhabian


Download Raspberry-Pi Imager at https://www.raspberrypi.com/software/


When you run it; It'll ask for…

  1. Operating System: scroll down and click "Other specific-purpose OS"

    • Pick & Click "Home assistants and home automation"

    • Pick & Click "openHAB"

      • Pick 32-bit as OpenHAB states use 32-bit; works best.

      • Storage: Choose the Flash-Card Target.


  1. Insert Card into Raspberry-Pi and attach an Ethernet Cable

    • Power the Raspberry Pi and wait a while for boot up process.

    • Connect to the openHAB UI at http://openhabian:8080

    • This may take up to 45-Minutes to become available

    • May have to use MS-DOS">arp -a" command to find it's IP-Address

    • Enter an administrator Username and Password on Startup.

    • Connect to the openHAB Log Viewer (frontail): http://openhabian:9001


7.2.2Putty


  1. Install PuttySSH Terminal on a Home PC.

    1. See: https://putty.org/

    2. Run the Putty terminal

      • Click on Connection Type: SSH

      • Enter Host Name: openhabian

      • click open.

    3. Login

      • Username: openhabian

      • Password: openhabian

7.2.3MQTT Broker & Client


  1. Login to the Server computer (Raspberry Pi) using ‘Putty’ terminal.

    1. Install the MQTT Broker (Mosquitto) on the Raspberry Pi.

openhabian:~$ sudo apt install mosquitto

openhabian:~$ sudo systemctl start mosquitto

openhabian:~$ sudo systemctl daemon-reload

openhabian:~$ sudo systemctl enable mosquitto

    1. Also install MQTT Client (mosquitto-clients) on the Raspberry Pi.

Openhabian:~$ sudo apt-get install mosquitto-clients

    1. Visit the above link for enabling outside IP connections if desired.


  1. Test the MQTT broker setup with mosquitto-clients.

    1. Login with a 2nd putty terminal and enter

openhabian:~$ mosquitto_sub -v -t 'test/topic'

    1. On the 1st putty terminal send an MQTT publish

openhabian:~$ mosquitto_pub -t 'test/topic' -m 'helloWorld'


verify that the (-m)message ‘helloWorld’ appears on the 2nd terminal.



7.2.4Serial2MQTT


  1. Install serial2mqtt

openhabian:~$ wget https://raw.githubusercontent.com/TGit-Tech/Tode-RC-Firmware/main/serial2mqtt_build/serial2mqtt.`arch`.zip


openhabian:~$ wget https://raw.githubusercontent.com/TGit-Tech/Tode-RC-Firmware/main/serial2mqtt_build/serial2mqtt.json


openhabian:~$ unzip serial2mqtt.`arch`.zip

openhabian:~$ mv Debug/serial2mqtt.`arch` serial2mqtt


  1. Setup crontab to auto-run serial2mqtt at start-up

    • Start the crontab editor

openhabian:~$ crontab -e

@reboot /home/openhabian/serial2mqtt


be sure to save / write changes to file.


  1. Check operation

    1. Reboot (Power-Cycle) the Raspberry Pi Server.

    2. Make sure ‘serial2mqtt’ starts after Raspberry Pi reboot

openhabian:~$ ps -x

PID TTY STAT TIME COMMAND

347 ? Ss 0:00 /bin/sh -c /home/openhabian/serial2mqtt

348 ? Sl 0:01 /home/openhabian/serial2mqtt

    1. View the ‘serial2mqtt’ logfile

openhabian:~$ tail -f log.serial2mqtt.0.log

    1. For debugging; you can launch ‘serial2mqtt’ from the command line.

openhabian:~$ ~/serial2mqtt

    1. Attach Tode to the Raspberry Pi by USB cable.

      • Watch the ‘serial2mqtt’ log file as it connects and publishes data.


7.2.5OpenHab


Inside OpenHab you can now add the MQTT binding which also requires an MQTT thing. Once the Tode publishes it’s ‘homie’ MQTT data the first time a ‘tode’ thing will show up in the ‘inbox’ feature.


However; due to OpenHab bugs after a ‘tode’ thing has been added one must instruct the Tode to send the ‘homie’ data a second time. Go to Todes SETUP menu, to ‘System’ menu and select ‘Pub ADiscv’ (stands for Publish Auto-Discovery data) and push the Okay button.


Only after OpenHab has received the ‘homie’ data a second time will the ‘channels’ show up. The rest of OpenHab setup should be instructed in the OpenHab guide.


The Tode publishes MQTT in the form of homie/tode/todename/devicename (gets) + /set for (sets).


It also publishes MQTT in the form of homie/tode/tstodename/tsdevicename where the ‘ts’ prefix stands for timestamped status. ‘ts’ channels are for (gets) only and appends a hexadecimal millisecond timestamp to the gotten value. ( example; ON-2fe3a1). Using OpenHab label card to show this (gotten) value ensures that the sets are preformed correctly. Watch that the timestamp changes after setting a new value.


A.MQTT /get Value Update


Once Widgets are setup to turn things on and off.

Using a Label Card to display “ts” values.


  1. Get the UID of the MQTT Broker by clicking the ‘Copy UID’ symbol.

  2. C
    reate New script named mqttGet

    1. Use ‘ECMAScript’

    2. actions.get("mqtt","mqtt:broker:58b97f2f4b").publishMQTT("homie/tode/1com6/get","")

    3. Paste your MQTT Broker UID in second get() parameter. And adjust the publish MQTT for the ‘TodeName’ for the /get.

  3. Setup the Label Widget to run the ‘GetScript’ when clicked.

    1. Under Action choose ‘Run rule’

    2. Click Rule and select ‘mqttGet’ for the ‘script name’.




7.2.5 MQTT Control :: OpenHab Server Setup :: OpenHab Page -23-