Tuesday, September 29, 2020

Travis CI and precompiled firmware for OHS 2.x

Over last weekend I've created a Travis continuous integration for OHS 2.x gateway repository. This CI performs a test build on every commit that is pushed to it. What it does is that it verifies that the commit is buildable, and maybe more importantly, it creates new compiled firmware related to every new commit, and places it back in releases section directly in GitHub.

This means that the latest, and also historical firmware are now available for download in https://github.com/vysocan/OHS_2-gateway/releases 

Binary files .bin can be directly used for DFU - Device Firmware Upgrade.

Wednesday, September 23, 2020

TCL scripts

TCL scripts is a new functionality in OHS 2.x. They allow various enhancements to be added by users to the automation part of the gateway. As the base of TCL language I used the following library: https://github.com/zserge/partcl, and embed it into gateway firmware. Scripts are handled by a separate thread that has a queue that serves all incoming scripts, and passes the result back asynchronously as a call back. Scripts are using their own separated heap, provided by umm_malloc library, that performs great heap management. Embedded SPI FRAM is used as storage for scripts with 64kB of available space. I have written a simple block access library called uBS (micro block system) that allows basic read write operations.

Scripts also have their own tab in the web interface, which allows you to create and run the TCL scripts directly on the gateway. As shown on the picture, there is statistics about the heap and the storage used by scripts. as well as helper icons </> and #. The </>, when you hover over it, shows build in language helps. And the # shows all variables currently in heap with their values.

Button "Run" passes the edited script into execution queue. "Refresh" button simply refreshes the page, allowing the "Last output:" to be seen. "Save" stores the script with given name to uBS storage, and allows this scripts to be assigned to triggers and timers.

Due to performance limitations, since scripts are not primary function of the gateway, there are build in limits to maximum script execution time, and maximum script interactions.

Language syntax

Tcl script is made up of commands separated by semicolons or newline symbols. Commands in their turn are made up of words separated by whitespace. To make whitespace a part of the word one may use double quotes or braces.

An important part of the language is command substitution, when the result of a command inside square braces is returned as a part of the outer command, e.g. puts [+ 1 2] performs addition of 1 + 2 and passes the result to puts.

Currently the only data type of the language is a string. Even numbers are stored in string format and converted to numeric types when needed.

Any symbol can be part of the word, except for the following special symbols:
  •     whitespace, tab - used to delimit words
  •     \r, \n, semicolon or EOF - used to delimit commands
  •     Braces, square brackets, dollar sign - used for substitution and grouping
 

Interpreter

Partcl interpreter is a simple structure which keeps the current environment, array of available commands and a last result value. Interpreter logic is wrapped around two functions - evaluation and substitution.

Substitution:
  • If argument starts with $ - create a temporary command [set name] and evaluate it. In Tcl $foo is just a shortcut to [set foo], which returns the value of "foo" variable in the current environment.
  • If argument starts with [ - evaluate what's inside the square brackets and return the result.
  • If argument is a quoted string (e.g. {foo bar}) - return it as is, just without braces.
  • Otherwise return the argument as is.
Evaluation:
  • Iterates over each token in a list.
  • Appends words into a list.
  • If the command end is met (semicolor, or newline, or end-of-file - our lexer has a special token type TCMD for them) - then find a suitable command (the first word in the list) and call it.
Each command has a name, arity (how many arguments is shall take - interpreter checks it before calling the command, use zero arity for varargs) and a C function pointer that actually implements the command. 
 

Builtin commands

  • "set" - assigns value to the variable (if any) and returns the current variable value.
  • "subst" - does command substitution in the argument string.
  • "puts" - prints argument to the tcl_stdout buffer, followed by a newline
  • "proc" - creates a new command appending it to the list of current interpreter commands. That's how user-defined commands are built.
  • "if" - does a simple if {cond} {then} {cond2} {then2} {else}.
  • "while" - runs a while loop while {cond} {body}. One may use "break", "continue" or "return" inside the loop to contol the flow.
  • Various math operations are implemented like:  !, +, -, *, /, >, >=, <, <=, ==, !=, &&, ||.
  • "string" - performs simple string manipulation, like"compare" and "length".
  • "clock" - allows time and date manipulation, like "seconds", "format" and "add".

Sunday, September 6, 2020

Gateway 2.x configuration

Just started to update new page section for gateway 2.x configuration. It can be find in menu on right. It will describe basics terminology for OHS, new shell interface for OHS 2.x gateways and of course a web interface used to configure the functionality.  Currently it is work in progress, but I will try to add all sections that are missing, and finish it as primary guide for new users.