Documentation

• How Teeken works
• Installation and basic setup
• How-To...
• The Ini-File Reference
• Things to come
• Appendix: Comma Separated Value (CSV) files

How-To...

• ... edit the configuration with only a text editor
• ... edit the configuration with Excel (or other spreadsheet app)
• ... connect to a Siemens 300 / 400 PLC via Ethernet
• ... connect to a Siemens 300 / 400 PLC via USB-MPI cable
• ... monitor inputs, data blocks, etc. of a Siemens PLC
• ... monitor data points of a Modbus device
• ... trigger an event / message
• ... trigger a scheduled / timed event or message
• ... detect that the PLC / machine is defect
• ... send messages by e-mail
• ... send e-mail through gmail / googlemail
• ... send messages to Twitter
• ... push events to a smartphone immediately
• ... log events to a file
• ... create daily / monthly / hourly log files
• ... start a program when an event occurs
• ... embed live values into messages
• ... poll a PLC/node only every n seconds
• ... run only one cycle / until an event occurs
• ... change the configuration during runtime
• ... start Teeken at Windows start-up
• Frequently Asked Questions (FAQ)
  • Low-cost Modbus I/O devices
  • Why no graphical Windows application?
  • Whats the maximum length of a message

... edit the configuration with only a text editor

Use a pure text editor like notepad or PSPad.

Make sure to save the file with CRLF as line endings.

... edit the configuration with Excel (or other spreadsheet app)

Most spreadsheet apps use the file extension to decide how to load a file. Therefore, teeken.ini should be renamed to teeken.csv or teeken.ini.csv.

When you Save as... with Open Office or LibreOffice, adjust the settings as follows:

• Charset: 'ISO-8859-1'
• Field delimiter: ';'
• Text delimiter: '"'
• Use double quotes for quotes within text: "text ""quoted"" text"

... connect to a Siemens 300 / 400 PLC via Ethernet

source;"MyPLC"
adr;simatic;tcp:192.168.0.7

Defines a source called "MyPLC" that

• is of type ´simatic`, i.e. a Siemens PLC
• connected via TCP/IP, i.e. Ethernet
• at the address 192.168.0.7

Notes:

• All node's following a source line will be coupled to that source
• The syntax of a node's address depends on the type of PLC

... connect to a Siemens 300 / 400 PLC via USB-MPI cable

source;"MyPLC"
adr;simatic;usb

Defines a source calles "MyPLC" of type simatic, i.e. a Siemens PLC, connected via USB. All following node's will be coupled to this connection.

The USB-MPI connections needs the Siemens "PC/PG-connection" which is part of the Step7 programming software. Therefore, Step7 must be installed. A valid Step7 license is technically not necessary, but might be legally required.

... monitor inputs, data blocks, etc. of a Siemens PLC

1. Define a source and connect it to a Siemens PLC

2. Define a ´node´ for each data point below the source

   node;a;i0.1;"Button 1";/mybuttons;N

Defines a data point ("node") coupled to this PLC that

• monitors input line 0.1 ("i0.1")
• will be triggered when it becomes non-zero ("N")
• produces the message text "Button 1"
• notifies all receivers in directory "/mybuttons"

Refer to Siemens' documentation for the format of valid addresses.

Teeken supports the following Siemens addresses:

• I, IB, IW, ID: Input bits, bytes, words, dwords
• O, OB, OW, OD: Output...
• F, FB, FW, FD: Flags...
• DBx.DBX, DBx.DBB, DBx.DBW, DBx.DBD: Data block bits, bytes, words, dwords
• T: Timers
• C: Counters

Teeken also supports the German address format:

• E for Inputs (Eingang)
• A for Outputs (Ausgang)
• M for Flags (Merker)
• Z for Counters (Zähler)

... monitor data points of a Modbus device

1. Define a source of type Modbus and connect it to the device. E.g.

   source;"myModbusdevice"
adr;modbus;tcp:192.168.0.22

   will connect to a device at IP address 192.168.0.22

2. Define some node's with proper Modbus addresses, e.g.

   node;a;1:1;"Sensor 1";"/ini";N
node;a;4:10;"Overheat";"/temps";O:200

This will produce an event message, whenever data point 1:1 becomes non-zero, rsp. when the value of data holding register 4:10 exceeds 200.

Teeken supports the following Modbus address ranges:

While data points 0:0..2:65535 can hold only single bits (0,1), inout registers (3:0..) and data holding registers (4:..) are always fetched as 16bit values. You can not monitor single bits in 16bit registers.

Modbus addresses in Teeken always start at 0. If your Modbus device uses addresses from 1, like e.g. Schneider PLC's, you probably have to subtract 1 from every address.

Addresses can be written with : as separator or fully decimal, i.e. 400000..465535 for 4:0..4:65535. Input lines start at 100000. Every number below that will be regarded as Output line address (0:0..0:65535) or error when >65535.

FC is the Modbus function code used to fetch the data. Please refer to the specification documents at modbus.org for details.

... trigger an event / message

Every data point holds a trigger condition, determining when to send a message, signal an event or write to a file.

The trigger condition can be one of the following:

Some examples:

... trigger a scheduled / timed event or message

Data points (nodes's) can be triggered by time conditions. The trigger keyword for this is "T", followed by the timing scheme for hours and minutes. The syntax for timer triggers follows the crontab scheme.

Teeken supports the following elements, which can be used independently for hours and minutes:

Notes:

• The hours are given in 24h mode, i.e. 13 = 1pm, 18 = 6pm, etc.
• The smallest time unit is one minute. T:*:* will be triggered every minute, which might be useful for log files (receiver type file).
• Timed events are only triggered when occurring during runtime. Teeken will not catch up missed events.
• You can send/log a heart beat signal using the special "!OFFLINE" address like this: node;a;!OFFLINE;heart beat;none;T:*:*. Teeken will send a new message every minute, even when the Source is not connected.

... detect that the PLC / machine is defect

Teeken support some pseudo-addresses for nodes to detect and report special situations. All pseudo-addresses begin with a "!" and are therefore called "bang-addresses".

node;a;"!OFFLINE";"This device is offline";"/machine";N

This node will be triggered (non-zero), whenever Teeken cannot communicate with the device. Use it like any other node to send or log a message.

... send messages by e-mail

If you set up Teeken to send messages by e-mail, it will send one e-mail per node that was triggered. To be able to do so, you'll have to set up the mail transport server and at least one receiver of type mail.

uplink;smtp;"smtp://mymailserver.com:25";"musername";"thepassword";"john.doe@gmail.com"
...
receiver;"tomymail"
adr;mail;"hello@example.com";
dir;/notes

1. Define the SMTP server to send mails through, where

   • "smtp:" defines unencrypted SMTP (use smtps: for SSL/TLS)
   • mymailserver.com is the server's address. You can also use an IP address for inhouse servers.
   • ":25" is the optional port number.
   • "myusername" and "thepassword" are needed to log into the mail server
   • "couple@example.com" will be the "from:" address of the notification mails

   Look below for a sample on how to use gmail as SMTP server.

2. Define a receiver, called "tomymail" of type "mail", that will send all messages to "hello@example.com"

The standard mail will look like this:

From: john.doe@gmail.com
To: hello@example.com
Date: Sat, 05 Oct 2013 18:00:37 -0700 (PDT)
Subject: Extruder: Fuse Fail

M: Fuse Fail
T: 2013-10-06 03:00:20
S: Extruder
A: e0.1
V: 0

Where

• The From: address comes from the SMTP-Definition
• The To: address is defined at the receiver
• The Subject: line contains first the source name of the node, followed by the text part
• The mail body contains
  • "M:" - the message (text)
  • "T:" - Date and time when the node was triggered
  • "S:" - the source name
  • "A:" - the address of the node
  • "V:" - the current value of the node

Notes:

• The SMTP account credentials are stored in Teeken.ini as plain text, vivisble for everyone who has access to the file
• You can define only one SMTP-Server and only one From-address
• You can define many receivers with different To-addresses
• Many mail servers will regard too many short e-mails from the same source as spam
• Think about embedding live values into the mail messages to send more than one data point per mail.

... send e-mail through gmail / googlemail

If you have a mail account with Google, i.e. an e-mail address like john.doe@gmail.com, you can use gmail.com as the transport service ("the SMTP server").

For this example, we assume

• your e-mail address is john.doe@gmail.com
• your password for gmail is mymailpassword

Set up the SMTP line in Teeken.ini like this:

uplink;smtp;"smtps://smtp.gmail.com";"john.doe";"mymailpassword";"john.doe@gmail.com"

The variable parts of the line are:

• "john.doe" - your user name (without the @gmail.com)
• "mymailpassword" - the password of the google account
• "john.doe@gmail.com" - the "From:" address

Please note:

• You must use the correct "From" address

... send messages to Twitter

Teeken can post messages to Twitter, either as status updates to the timeline or as direct messages to a dedicated Twitter user.

Before Twitter will accept messages from Teeken, you must authorize it with Twitter. Use PLCTwithAuth to obtain the necessary keys from Twitter. This will generate a file named "PLCTwitKeys.ini" that should be stored in the same directory as Teeken.exe. Use login and password of the Twitter user that will appear as the sender of the tweets.

To post messages publicly into the senders timeline, create a receiver for Twitter in ´Teeken.ini`

receiver;"TweetThis"
adr;twitter

To send messages directly to a Twitter user, use their screen name as a parameter

receiver;"TweetDirect"
adr;twitter;"@tothisuser"

Please note, that

• all tweets and direct messages are sent from the same Twitter account (the sender)
• you can only send direct messages to users who are following the sender
• Twitter will reject recurring tweets or messages with the same text

... push events to a smartphone immediately

Instant alerts on smartphones, known as push notifications, need a complex infrastructure of apps, servers and identification procedures multiplied by the number of platforms and operating systems for smartphones. This is beyond the reach of the Teeken application.

There are, however, other ways to receive instant alerts when a Teeken node is triggered.

Several services like Pushover provide methods to forward e-mails as push notifications to iPhone and Android. It works like this:

1. Install the app on your smartphone
2. Create an account at Pushover from within the app.
3. Log into the Pushover website
4. Copy the e-mail address shown under "Your User Key"
5. Define a receiver of type mail and the mail address from Pushover in Teeken.ini

Other services like Pushover are (as of July 2014):

Boxcar.io (iPhone / iPod touch only)

Install the Boxcar app onto your iOS device

Every installation receives a unique e-mail address from boxcar.

Use this address as destination for your receiver

If This Than That

Install the IFTTT app onto your mobile device (iOS, Android)

Set up the email channel in IFTTT with the e-mail address

Create a recipe with a trigger of Send IFTTT an email

Choose a suitable action for notification, like Notification or SMS or even Twitter

... log events to a file

node;a;c10;"Counter 10: {{*}}";/mycounters;T:*:*
receiver;"Counter-Log"
adr;file;"mylogfile.csv"
dir;/mycounters

• defines a node that

  • monitors Counter 10 (c10)
  • will be triggered every minute
  • produces a text message "Counter 10:" followed by the current value of c10
  • notifies all receivers in directory /mycounters

• defines a receiver

  • with the name "Counter-Log"
  • of type file with` the name "mylogfile.csv"
  • that receives all notifications in directory /mycounters

Therefore: Every minute, a new message with the current value of Counter #10 (c10) will be added to file "mylogfile.csv".

File names SHOULD contain the full directory path, like `"C:/logs/mylogfile.csv"´. You can use "/" or "\" for directory paths.

Messages in files have the format <sourcename>;<adr>;<date>;<time>;<value>;<text>, where

• <sourcename> and <adr> are source and address of the signaling node
• ´´ and ´´ are ISO-formatted (year-month-day, hour:minute:second)
• <value> is the current value of the node's data point (i.e. c10 in our example)
• ´´ the text message

A line in "mylogfile.csv" will look like

"MyPLC";"c10";2013-09-15;17:23:05;27;"Counter 10: 27"

... create daily / monthly / hourly log files

The file name of a receiver of type file may contain template symbols of strftime.

The most interesting template symbols are probably

• Week numbers: week one starts with first Sunday (%U), first Monday (%W) or ISO (%V)

Examples:

... start a program when an event occurs

receiver;"aStarter"
adr;exec;"C:/programs/myapp.exe"

Defines a receiver that will start "myapp.exe" for every message it receives.

• A full path should be specified for the program
• Parameters may be given with the program, like "C:/programs/myapp.exe -c something"

The programm will get the message data appended to its command line as one string. The message is formatted as a log file line.

Example:

For the node node;a;c10;"Counter 10: {{*}}";/mycounters;T:*:* (see "... log events to a file") and the receiver above, Teeken will call

C:/programs/myapp.exe ""MyPLC";"c10";2013-09-15;17:23:05;27;Counter 10: 27"

... embed live values into messages

The text part of a node definition can contain references to any data point address of the same source.

References are written as absolute data point addresses, embraced in {{}}.

For example: 'node;a;e0.1;"Pieces made: {{DB4.DBW2}}";/mycounters;N' will be triggered when e0.1 becomes non-zero. The message text will be "Pieces made:", followed by the current value of DB4.DBW2.

A special address is {{*}}, which refers to the data point address of the node itself.

Example: 'node;a;c10;"Counter 10: {{*}}";/logger;T:*:*' will create a message like Counter 10:, followed by the current value of c10. It will be triggered every minute (T:*:*).

... poll a PLC/node only every n seconds

Teeken can be slowed down on three levels: 1) global (all sources), 2) on source level, 3) on node level

coupler;readinterval;<seconds> tells Teeken to pause <seconds> seconds between read cycles. No communication with devices or receivers will occur during the interval. Changes in node values may occur unnoticed.

set;readinterval;<seconds> can be written after a source or node line and does the same as above, but only for this source or this node.

Global settings beat local settings and source settings beat node settings. The global setting should therefore always define the shortest pause in the system.

... run only one cycle / until an event occurs

coupler;runmode;<mode> tells Teeken when to stop.

Default value, when no coupler;runmode is given, is cycle.

... change the configuration during runtime

Teeken checks wether the configuration file was changed and re-reads it, if so. To be sure that all changes are valid, the new configuration must be unchanged for 10 seconds.

To change the configuration during runtime:

1. make a copy of the current configuration
2. edit the copy
3. overwrite the original file with the new version.

PCcoupler will detect the change about 10 seconds after the original file has been overwritten.

When a new configuration is detected, Teeken will

• terminate all connections
• re-read the configuration
• restart the connections

which is basically the same process as stopping and restarting Teeken.

Depending on the number of connections and connection types, this will take a few seconds.

... start Teeken at Windows start-up

1. Install Teeken
2. Write and test your configuration (Teeken.ini)
3. Go to Settings, Control Panel, Scheduled Tasks
4. Create a new task
5. Locate teeken.exe
6. Use When my computer starts
7. Open Advanced Properties
8. Ensure that Start in: points to the directory of teeken.exe

Frequently Asked Questions (FAQ)

Low-cost Modbus I/O devices

If you need some digital or analog inputs, counters, etc. to be monitored by Teeken, look for example here:

• Wago Modular I/O. The 750 and 753 series with Ethernet fieldbus coupler responds to ModbusTCP. Digital and analog inputs available, also counters. Optional PLC modules can add intelligence.
• Schneider-Electric Momentum. The Ethernet version supports ModbusTCP. No counters, no analog inputs.
• Schneider-Electric Twido is a tiny, but complete PLC. Counters and analog values must be implemented in a Twido program.

Why no graphical Windows application?

Teeken is a pure "console application" without the normal graphical window, which has the following benefits:

• The executable has a very small footprint
• It needs no desktop, nor user account
• It is independent of video resolution
• It can run in background from Scheduled Tasks

Whats the maximum length of a message

The internal maximum of a fully expanded text message including embedded live values is 4000 characters. Some uplinks like Twitter have lower limits, so Teeken will shorten messages send to them. Twitter messages will be cut at 140 characters.

Known limits are:

• Twitter messages (including the "d @username" part) will be cut at 140 characters
• E-mail subject lines will not be cut, but some mail transport servers may refuse long lines