Tode-RC
Users Guide
Setup and Operation
Firmware Version: 232H
Last Updated: 2023-02-22

1.Contents
2.Introduction
The Tode Project is a Universal Platform of...
User Inter-Face Options
Back-plane Models optional Radio & Arduino Micro-Controller
Extensions - IO Interfaces, Battery Trays
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
Remote-Control Tested Distance
Test Setup
(2) Todes set at Tx Power 30dbm
(2) Todes having a 5dbi 20cm Omni antenna
Stationary Tode antenna mounted 12ft above ground level
Rural Area.
Signal can reasonably be used at 2-miles away
Signal can be spot gotten (hard to get) at 3-miles away
There is no signal past 3-miles
2.2Menu Structure
Multiple Todes make-up a remote-control network-of Individual Todes.
The particular Tode in subject is self-described as This-Tode.
Each Tode that is accessible on This-Tode has its own Tode-Screen.
Tode-Screen are ordered Horizontally
Left-most = This-Tode ( use
button to switch left )
Right-most = Last Remote-Tode accessible (use
button)
-
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
Sub-Level Menu Screens ( From This-Todes SETUP Screen )
Selecting Radio and
will produce Sub-Level Radio Settings.
Selecting Add Device and
will produce Add a Device Screen.
Selecting Del Tode and
will produce List of Todes.
To Exit a Sub-Level Screen press the
button.
3.Configure
3.1Set Name
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
Radio Settings that must be identical for Tode Communication.
-
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.
Radio Setting that must be Unique
-
Address
(Range 0000-FFFE)
A radio address to identify each Tode uniquely decided upon by you.
Other Radio Settings
-
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
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.
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.
In this example Address is set to 1112.
3.2.3Value Setting
Choose any Frequency between 410MHz and 441MHz (default is 433MHz).
The chosen frequency must be identical on all Todes expected to communicate with each other.
-
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
Choose the lowest Tx Power level that will sustain communications.
3.3IO HDW Setting
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.
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
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: OLoOffOutput 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)
To Remotely Control another Todes Devices.
The “Remote” Tode (RC1 with RELAY1:IO-Device used this far)
is added to a new Tode (RC2)
Obtain a 2nd Tode
Repeat Steps 3.1.Set Name and Name the 2nd Tode RC2
Assign a *Unique* Radio Address to RC2
-
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
Every Device Setup has a Del Device option.
Every Pin has a corresponding pinMode option.
OLoOff = Output Low, when Off – Active High
OHiOff = Output High, when Off – Active Low
InHigh = Input Pull-Up(High) – Active Low
InLow = Input Low – Active High (Default Setting)
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.
USBSerial allows (3)options
NOTICE: Changing the USB-Serial use causes an auto-reboot to occur.
None = There is no USB Serial Usage (option for debugging)
MQTT = Tode uses USB Serial to communicate with MQTT Server.
KBC = Keyboard Control by Serial Input. (For Automated Testing)
8=up 9=Set
4=left, 6=right
2=down 3=Get
Factry RST erases all Todes and Devices and User-Settings.
Pub ADiscv publishes ‘homie’ auto-discovery MQTT on-demand.
only works when USBSerial=MQTT.
SRFWv preforms a soft (no-erase) reset on-demand and also displays the loaded firmware version. It can be used to reset without power-cycling after making a new setting for USBSerial or any reason to do just a soft-reset.
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…
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.
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
Install PuttySSH Terminal on a Home PC.
See: https://putty.org/
Run the Putty terminal
Click on Connection Type: SSH
Enter Host Name: openhabian
click open.
Login
Username: openhabian
Password: openhabian
7.2.3MQTT Broker & Client
Login to the Server computer (Raspberry Pi) using ‘Putty’ terminal.
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
Also install MQTT Client (mosquitto-clients) on the Raspberry Pi.
Openhabian:~$ sudo apt-get install
mosquitto-clients
Visit the above link for enabling outside IP connections if desired.
Test the MQTT broker setup with mosquitto-clients.
Login with a 2nd putty terminal and enter
openhabian:~$ mosquitto_sub -v -t
'test/topic'
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.
Online Instructions for installing an MQTT broker on Raspberry Pi.
7.2.4Serial2MQTT
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
Setup crontab to auto-run serial2mqtt at start-up
Start the crontab editor
openhabian:~$ crontab -e
Edit the file adding the following line at the bottom of the file.
@reboot
/home/openhabian/serial2mqtt
be sure to save / write changes to file.
Check operation
Reboot (Power-Cycle) the Raspberry Pi Server.
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
View the ‘serial2mqtt’ logfile
openhabian:~$ tail -f
log.serial2mqtt.0.log
For debugging; you can launch ‘serial2mqtt’ from the command line.
openhabian:~$ ~/serial2mqtt
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.
Get the UID of the MQTT Broker by clicking the ‘Copy UID’ symbol.
C
reate New script named mqttGetUse ‘ECMAScript’
actions.get("mqtt","mqtt:broker:58b97f2f4b").publishMQTT("homie/tode/1com6/get","")
Paste your MQTT Broker UID in second get() parameter. And adjust the publish MQTT for the ‘TodeName’ for the /get.
Setup the Label Widget to run the ‘GetScript’ when clicked.
Under Action choose ‘Run rule’
Click Rule and select ‘mqttGet’ for the ‘script name’.
7.2.5 MQTT Control ::
OpenHab Server Setup
:: OpenHab
Page -