back to developer home

By learning how the ACS Block System works, you can use the Block System to new types of touchatag Applications.

After learning the fundamentals of the Block System, you define new applications using a Specification Document.

Overview

All touchatag Applications are powered by a modular execution engine called the Block System, which is a component of the touchatag Application Correlation Service (ACS).

Each time a tag is touched to a reader or a QR Code is scanned, the Application Correlation Service (ACS) correlates the tag to an Application. As soon as the Application is identified, the ACS dispatches a job to the ACS Block System.

The Block System is so named because it provides a set of re-usable building blocks that you can assemble into the complete logic of a touchatag Application. Each block provides different functionality for the Application, such as sending instructions to the touchatag client, or calling an external web service.

You assemble blocks into a touchatag Application by creating an XML document called a Specification. Before creating your first Specification, there are some important concepts to understand about the Block System. These include Blocks, Superblocks, Applications, and Wiring.

Once familiar with these concepts, you can proceed to learn how to compose a technical Specification for an application that implements one or more Blocks, as documented in the Specification docs.

Finally, for those who enjoy knowing things just a little deeper, you will find a short appendix of Deeper Technical Information.

Blocks

Blocks are the most basic units of logic in the Block System. They represent the most fundamental features available within the ACS.

Every Block has one or more Pins, which provide the block with runtime interfaces for input and output. When you link various Blocks together, you do so by connecting output pins to input pins in a Wiring Scheme.

Many Blocks also have Properties. Properties function as configuration interfaces, allowing you to assign configuration values that are needed within a touchatag application. The value set for a property can be obtained from a given block through an output Pin.

Each Block available in the ACS Block System also has a Block Identifier, which is a unique name comprised of the block's namespace and the block's name. (All blocks in the ACS Block System's library use the reserved namespace urn:touchatag:block, plus the block's unique name.

To put these concepts into context, let's look at a couple block examples from the Block Reference documentation.

Example 1: The TextSource Block

The TextSource block provides a simple first example. You can use the TextSource block to provide a string of text to another block.

In the image at right, notice in the summary that the TextSource block has one property, named Value, and one output pin, named out.

It has no input pins, because the TextSource block's whole purpose is to provide the text in its Value property to other blocks through its output pin.

In order to understand how this block might be used in conjunction with other blocks, let us consider a second example.

 

 

 

Example 2: The Message Block

The Message block sends a system tray notification message to the end user's computer.

In the image at right, notice that the Message block has one input pin, one output pin, and no properties. It has no properties because, like many blocks in the ACS Block System library, it was designed to be simple and functional.

The input pin, named in, can be wired to accept text data.

The output pin (out) is an action for the ACS to perform, which in this case is to send a message from the input pin text to the end user's system.

As you can see, the Message block requires a text input in order to perform its action. In the previous example, the TextSource block has a text output. The TextSource block can provide what the Message block needs by wiring the TextSource's out to the Message block's in.

Note You can jump ahead and see how this would look in a Specification in the System Tray Notification Specification example.

Superblocks

A Superblock encapsulates other smaller blocks (and even other superblocks) to create a single, functional unit that can be used just like any other block.

As with a block, a superblock may have input and/or output pins, as well as properties. Although you use a superblock just as you use a block, the benefit of the Superblock is that it abstracts the assembly of blocks it contains, making it a single construct to use and re-use instead of re-assembling its constituent blocks each time you need them.

On its inside, a Superblock has three sections:

1. Properties, which may be used by any of the blocks within the Superblock
2. Breakdown, which lists the blocks used in the Superblock, assigning each a unique name (id).
3. Wiring Scheme, which identifies how each of the Superblock's internal blocks connect together at runtime.

Let's consider another example, this time using the XML notation for a Superblock.

Example 3: System Tray Notification Superblock

In the previous two examples, we saw two blocks that would work well together as a simple, yet functional, touchatag Application. The following XML is excerpted from the Specification document example for System Tray Notification. In it, identify the three sections of the Superblock, and consider how they relate to one another.

...    <superblock id="urn:example:sample:message-app">       <property name="Message">          <text>Ta-dah!! Your tag has been read!</text>       </property>       <breakdown>          <block id="MsgText" ref="urn:touchatag:block:text-source">             <property name="Value"><delegate as="Message"/></property>          </block>          <block id="MsgBlock" ref="urn:touchatag:block:message" />       </breakdown>       <wiringscheme>          <wire from="MsgText:out" to="MsgBlock:in" />             <shunt from="MsgBlock:out" to="action-out" />       </wiringscheme>    </superblock> ...

Let's do a brief analysis of this Superblock's three sections.

1. You can see that the Superblock has one property, called Message.
2. You can see that the Breakdown identifies two blocks. The block whose id is MsgText is a TextSource block (urn:touchatag:block:text-source). The other block, with an id of MsgBlock, is a Message block (urn:touchatag:block:message).
   • The assigned id values give a unique name for each instance of a given block. So if your Superblock needed to use an additional TextSource block, you can add another and assign it a unique id.
   • Notice that the TextSource block's Value property is not assigned directly, but is delegated from the value of the Superblock's Message property. When constructing more complex Superblocks, where many blocks may need the same value, delegating properties simplifies the re-use of your Superblocks.
3. In the Wiring Scheme, you can see how pins are named using blockid:pinname, and how output pins are wired to input pins.
   • For now, consider shunt to be the same as wire. shunt is covered below under Wiring.

There are some pre-made superblocks in the ACS Block System library. However, over time, you will likely start creating your own superblocks that you re-use in various applications.

Applications

All touchatag Applications—whether the simple Web Link application or the multi-tag Music Cube application—are built using a type of block called an Application. Because an Application block describes a complete touchatag application, an Application block is actually the same as a Specification document.

As with blocks and superblocks, an application has pins and properties. Applications also have two components not found in other block types:

1. Commands
2. A Pre-defined Runtime Interface

Commands

A Command represents a distinct operation to which one or more touchatag tags can be associated.

Remember, a touchatag application may use more than a single tag. For example, the Music Player Application uses a physical cube with a tag on each of its six faces. Each tag is mapped to a different command within the same overall application. 

Example 4a: Commands in the Web Link Wheel Application

Let's examine the commands in a Specification Example for the Bidirectional Web Link Wheel. This is an application opens web links from a list. One command moves forward to the next link, the other backwards to the previous.

We can see how these two commands are represented in the application section of the complete Specification example for this application:

...    <application>       <command id="next" name="Show next link"/>       <command id="previous" name="Show previous link"/>    </application> ...

The command id is the identifier used within the Application. The name is a friendly name that end users see in the Configurator when associating the application with tags, as shown at right.

Of course, this raises questions. How does the application know which tag has been used? That brings us to command-id-in, which is part of the Application's pre-defined runtime interface.

Pre-defined Runtime Interface

Every Application has a set of predefined pins that allow it to get initial contextual runtime information from the ACS, and then output an Action back to the ACS.

Input Pins

Each of the input pins provides contextual runtime information to the application. These data types are:

• client-user-in provides the username configured in the touchatag client.
• command-id-in provides the id of the Command that triggered the application (see Example 4a, above)
• configuration-id-in provides the unique id of the Application Configuration to which the read tag is associated. (Each time you make a specific configuration of an application through the touchatag dashboard, that instance of the application is assigned a unique id.)
• tag-event-type-in provides the type of Tag Event that triggered the application. There are two possible values, one for each of the two types of reader event that are currently supported:
  • PUT (tag maintains on reader)
  • TOUCH (tag has been briefly seen by the reader and is no longer on the reader)

Output Pin

Every application must result in an Action. This action is identified on the output pin:

• action-out assigns the Action for the touchatag client to execute. (You must wire this output pin an internal block's action output. If you do not want the client to perform any action, there is a NoAction block.)

Using the Application Block's Runtime Interface

Every Application Block contains a single superblock as the parent container for any other blocks it uses. You can assign the application's properties within this superblock. (The application block can also have its own Properties section. This is usually done whenever using a pre-defined application block as the blueprint superblock within an application.)

Example 4b: Superblock in the Web Link Wheel Application

Let's once again consider the Specification Example for the Bidirectional Web Link Wheel, and observe how it uses the Application runtime interfaces (highlighted in red) in its wiring scheme:

...    <wiringscheme>       <shunt from="command-id-in" to="t2i:in"/>       <wire from="t2i:out" to="cu:in"/>       <wire from="cu:out" to="wl:in"/>       <shunt from="wl:out" to="action-out"/>    </application> ...

You can see that it connects command-id-in to the in pin of a block named t2i (which you will find in the full Specification) is a text-to-integer-mapping block, which simply assigns +1 to the next command, and -1 to the previous command).

You can also observe that the wl (WebLink) block's out pin is wired to the application's action-out pin.

Now, it's time to define the difference between shunt and wire.

Wiring

Let us now go into more detail on wiring. As previously stated, you must wire individual blocks together using their input and output Pins in a Wiring Scheme according to the functionality you desire.

All pins have a direction (input or output), and a type (kind of information that is required by, or available from the pin).

In a composition of blocks there is always an aggregating construct—either a superblock or an application—and its constituent blocks. (Some of these constituent parts may themselves be aggregates.) There is an important difference in wiring between constituent parts or wiring between an aggregating construct and one of its constituents.

• Wire: A connection between an output pin and an input pin between two constituents (green in image)
• Shunt: A connection between pins with the same direction (output to output, or input to input), where one pin belongs to the aggregating construct, and the other pin belongs to a constituent (blue in image)

Next Step

Now that you have learned how the Block System works, move on to learn how to construct Specification documents to define new applications.

Deeper Technical Information

Want to delve deeper? Here is some deeper technical information about the ACS Block System.

Execution Flow in the Block System

The Block System uses a simple execution flow based on a technique called Spreading Activation.

It basically means that it starts out with one or more active pins and then follows which pins become active as the activation spreads across the wiring scheme. The ACS is responsible for activating the starting pins (the application block's runtime interface input pins). When creating a specification for an application, you must ensure that after all activations have spread, the action-out pin is activated with an action. Whatever the action may be (including No Action), it completes transaction with the invoking client.

Certain blocks, such as the TextSource block, have self-activating pins. Thus it is possible not to use any of the application's runtime interface input pins in order for an application to work as intended. One or more of these self-activating pins can trigger its execution just as well.

For the execution flow all Superblocks (including the overall application block) are reduced to their constituent Blocks until our wiring scheme only exhibits the most basic Blocks. In this scheme the spreading activation will propagate all active pins where a block activates its output pins only when all of its input pins are activated. (Please note that a Superblock can contain multiple independent blocks and thus does not necessarily require all its inputs to be active before some of its outputs become active)

There are some special Blocks that only exhibit an output pin or only an input pin. Blocks with only an output pin are always activated. They typically output a value that was provisioned via a property, or is generated (e.g. random, current time). Blocks that only have an input pin stop the spreading from that block onwards. They are also blocks that perform a function that does not result in an action-out, such as writing data, or sending an e-mail.

As a result of the above, your applications do not require a single path from an application input pin to an application output pin. You can have several self-activated paths that are only executed for their side-effects and another path that actually wires to the application output pin. Only the latter is required.

Register Blocks

Each TagEvent triggers the execution of an Application. It is possible to maintain state between between several executions of an Application through a special type of blocks, called Registers. A Register is a special Superblock consisting of two Blocks, one that only has an output pin to emit a value and one that only has an input pin to store a value. These two Blocks actually write to the same underlying data storage and thus can maintain state between executions. A register will thus output its current value with its output pin, which is automatically activated and allow you to update that value by feeding it the updated value via its input pin.

Applications are Compiled on the touchatag ACS

Naturally, for applications that use multiple tags and have extremely large, sophisticated Specification files, XML would not the most efficient use medium for the ACS. To optimize Application response times (especially considering the mass number of tag transactions performed by the touchatag ACS), the ACS compiles all applications from their original Specification files into the ACS platform's native language.

Goals Behind the Creation of the ACS Block System

The Block System The Block System was created with these goals:

• Ensure that touchatag applications offer end users a consistent quality of experience
• Offload many of the runtime execution responsibilities from 3rd party applications
• Alleviate the complexities of RFID correlation from 3rd party developers
• Facilitate re-use of common constructs/features towards 3rd parties
• Provide the first step toward an application builder for non-developers