Start building a language for Things here.

Quick Start

This example demonstrates the basics of an Argot based language. It guides you through the general process of writing an Argot dictionary, as well as writing an object to a stream.

It is written using Java as this is the most complete implementation of Argot right now. You can download the Eclipse project to try it out.

  1. Download the file argot-quick-start-1.3.b3.zip.
  2. In Eclipse select File->Import.
  3. Select "General->Existing Projects into Workspace".
  4. Select "Archive file" and browse to the download.
  5. Select finish.

Define the format

The first step with Argot is defining the language. These are the data structures that the device or application uses in the messages they send and receive. Here's a few simple messages for a coloured light. It defines a colour type with red, green and blue. Following this, the set_colour message shows a reference to the colour data type.

cluster light;

definition light.colour 1.0:
{
	@red   #uint8;
	@green #uint8;
	@blue  #uint8;	
};

definition light.set_colour 1.0:
{
	@colour #light.colour;
};

It's important to note that the Argot language is designed around describing binary data. For example, the encoding of the colour data type is three unsigned single bytes (uint8) in a sequence. In addition, as the set_colour only references the colour type, it uses exactly the same number of bits as the colour type. The colour object as a stream would be encoded as follows:

		-----+--------+--------+--------+-------
		     | 8 bits | 8 bits | 8 bits |
		-----+--------+--------+--------+------
		         red    green     blue

Define the types in your language

The next step is to define how the various types are represented in the host language. Here's an example of the colour data type in Java.

@ArgotMarshaller(ArgotMarshaller.Marshaller.ANNOTATION)
public class Colour 
{
	public static final String TYPENAME = "colour";
	
	@ArgotTag("red")
	public short red;
	
	@ArgotTag("green")
	public short green;
	
	@ArgotTag("blue")
	public short blue;
}

Argot has different types of marshallers depending on the data being represented. You are also free to write your own marshaller for specific types if required. This can be useful when dealing with complex data structures.

Load and bind the library

In Argot, all data types are stored in a type library. With the data types defined and the object created in Java, the next step is to compile and load the type library.

typeLibrary = new TypeLibrary( );
ArgotCompilerLoader loader = new ArgotCompilerLoader("light.argot")
{
	public void bind( TypeLibrary library )
	throws TypeException
	{
		library.bind( library.getTypeId(Colour.TYPENAME, "1.0"), Colour.class );
		library.bind( library.getTypeId(SetColour.TYPENAME, "1.0"), SetColour.class );
	}
};
typeLibrary.loadLibrary(loader);

Write information to stream

To write out the information to an output stream, a SetColour instance is created. A TypeOutputStream is created which maps the object to the stream. The TypeMap provides the ability to perform type agreement and restrict the specific types used on a specific data stream. This will be covered in depth in future examples.

// Prepare the output stream.
ByteArrayOutputStream out = new ByteArrayOutputStream();
TypeMap typeMap = new TypeMap( typeLibrary, new TypeMapperDynamic(new TypeMapperCore(new TypeMapperError())));
TypeOutputStream typeOut = new TypeOutputStream( out, typeMap );
				
// Write the object.
Colour colour = new Colour((short)120,(short)10,(short)30);
SetColour setColour = new SetColour(colour);
typeOut.writeObject( SetColour.TYPENAME, setColour );

The setColour instance is written as an object to the stream. Argot performs the marshalling based on the Argot specification. The result of writing the colour object to the stream is that three bytes are written to the byte array.

Read information from a stream

To read the setColour message from the data stream, a TypeInputStream is created. The object is marshalled from the stream when given the Argot type name.

ByteArrayInputStream in = new ByteArrayInputStream(data);
TypeInputStream typeIn = new TypeInputStream( in, typeMap );
SetColour readSetColour = (SetColour) typeIn.readObject( SetColour.TYPENAME );

That completes this basic example of using Argot. More examples will be provided in the future.