RifidiWiki - User contributions [en]

Edge Management

2015-11-19T23:07:55Z

Nurban: /* Restlet Tuning/Confguration (Jetty) as of Rifidi 3.4 (coming winter 2015) */

=Introduction=
Starting in 3.1 Edge Management is now accessible though Restful Services (leveraging [http://restlet.com/ Restlet plugin]. Restlet allows all Rifidi Edge Management operations available through workbench to be accessible via Restful Services.Prior to Rifidi 3.1 Edge Management is available through RMI (currently used by Rifidi Workbench if looking for code examples).

The types of operations available through Restful Services include:
*All "session" commands (for stopping and starting reader/sensor sessions)
*ExecuteCommand and deleteCommand (for commands supported by a sensor such as a tag read)
*Readers (for getting a list of readers/sensors available on Edge Server instance)
*Commands (for issuing command line operations such as saving the Edge Server Configuration currently in memory)
*Get and Set Properties (for setting and getting sensor properties such as Setting the LLRP Reader Configuration dynamically)
*Create Reader (for creating a new reader connection)
*Managing Rifidi Applications (for stopping/starting, listing and deploying Rifidi Apps)

Additional features can be found on [http://restlet.com/ Restlet User Guide ]

=Configuration=

In rifidiserver.ini - A full list of Rifidi Edge configuration parameters can be found [[Edge_Server_Configuration]]
<pre>
#Port can be set
-Dorg.rifidi.restlet.port=8111
#Restlet starts by default this can be changed
-Dorg.rifidi.restlet.enabled=true

</pre>
Source for Restful Rifidi Management Commands - https://transcends.svn.cloudforge.com/rifidi/rifidi/trunk/org.rifidi.edge/src/org/rifidi/edge/rest/

=Configuration (HTTP over SSL) - Available as of version 3.1.1=

A full list of Rifidi Edge configuration parameters can be found [[Edge_Server_Configuration]]
<pre>
#SSL Port can be set
-Dorg.rifidi.restlet.ssl.port=8183
#Restlet starts by default this can be changed
-Dorg.rifidi.restlet.ssl.enabled=true
#Keystore Path
-Dorg.rifidi.restlet.ssl.keystorepath=\config\serverX.jks
#Key store password
-Dorg.rifidi.restlet.ssl.keystorepassword=password
#Key Password
-Dorg.rifidi.restlet.ssl.keypassword=password
#Key store Type
-Dorg.rifidi.restlet.ssl.keystoretype=JKS

</pre>

*Note: Link to how to configure/setup certificates with REST - http://restlet.com/learn/guide/2.3/core/security/https
==REST HTTP over SSL Example Application==
link to https java client example - https://transcends.svn.cloudforge.com/rifidi/rifidi/trunk/org.rifidi.edge.rest/src/org/rifidi/edge/rest/test/HttpsTestClient.java

<pre>
user can add this jvm parameter to see detailed messages if getting any
trouble when running this example:
-Djavax.net.debug=all

In order t0 successful get the https response from stand alone java
example, user must import the certificate into JVM:

open command windows as administrator and execute keytool -import, like:

keytool -import -alias localhost -keystore "C:\Program Files
(x86)\Java\jdk1.6.0_45\jre\lib\security\cacerts" -file
"D:\tmp\cert\localhost.cer"

if requested, default password is: changeit
</pre>

=Restlet Logging=

*1. Add an entry to the rifidiserver.ini (if using windows; when using linux you add this JVM argument in the rifidi-server executable):
-Djava.util.logging.config.file=d:/myLogging.properties

*2. Create logging properties file, for example like the below myLogging.properties
The entry in that file that determines where the log file will show up is the following: java.util.logging.FileHandler.pattern=d:/restlet.log

<pre>
myLogging.properties
# ================================
# == ==
# == Web Logging Properties ==
# == ==
# ================================

# ------------------
# General properties
# ------------------

# This defines a whitespace separated list of class names for handler classes to load and register as handlers on
# the root Logger (the Logger named ""). Each class name must be for a Handler class which has a default constructor.
# Note that these Handlers may be created lazily, when they are first used.
handlers=java.util.logging.FileHandler
# ------------------
# Loggers properties
# ------------------

.level=WARNING
org.mortbay.level=WARNING
org.restlet.level=INFO
com.noelios.level=WARNING

com.noelios.web.WebComponent.www.level=INFO
com.noelios.web.WebComponent.www.handlers=com.noelios.restlet.util.AccessLogFileHandler
com.noelios.web.WebComponent.www.useParentHandlers=false
# -------------------------
# ConsoleHandler properties
# -------------------------

# Specifies the default level for the Handler (defaults to Level.INFO).
# java.util.logging.ConsoleHandler.level=WARNING

# Specifies the name of a Filter class to use (defaults to no Filter).
# java.util.logging.ConsoleHandler.filter=

# Specifies the name of a Formatter class to use (defaults to java.util.logging.SimpleFormatter).
# java.util.logging.ConsoleHandler.formatter=

# The name of the character set encoding to use (defaults to the default platform encoding).
# java.util.logging.ConsoleHandler.encoding=

# ------------------------------
# General FileHandler properties
# ------------------------------

# Specifies the default level for the Handler (defaults to Level.ALL).
# java.util.logging.FileHandler.level=ALL

# Specifies the name of a Filter class to use (defaults to no Filter).
# java.util.logging.FileHandler.filter=

# Specifies the name of a Formatter class to use (defaults to java.util.logging.XMLFormatter)
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

# The name of the character set encoding to use (defaults to the default platform encoding).
# java.util.logging.FileHandler.encoding=

# Specifies an approximate maximum amount to write (in bytes) to any one file.
# If this is zero, then there is no limit. (Defaults to no limit).
java.util.logging.FileHandler.limit=10000000

# Specifies how many output files to cycle through (defaults to 1).
java.util.logging.FileHandler.count=100

# Specifies a pattern for generating the output file name. (Defaults to "%h/java%u.log").
# A pattern consists of a string that includes the following special components that will be replaced at runtime:
# "/" the local pathname separator
# "%t" the system temporary directory
# "%h" the value of the "user.home" system property
# "%g" the generation number to distinguish rotated logs
# "%u" a unique number to resolve conflicts
# "%%" translates to a single percent sign "%"
java.util.logging.FileHandler.pattern=d:/restlet.log

# Specifies whether the FileHandler should append onto any existing files (defaults to false).
# java.util.logging.FileHandler.append=
# -------------------------
# LogFileHandler properties
# -------------------------

# Specifies the default level for the Handler (defaults to Level.ALL).
# org.restlet.engine.log.AccessLogFileHandler.level=ALL

# Specifies the name of a Filter class to use (defaults to no Filter).
# org.restlet.engine.log.AccessLogFileHandler.filter=

# Specifies the name of a Formatter class to use (defaults to java.util.logging.XMLFormatter)
org.restlet.engine.log.AccessLogFileHandler.formatter=com.noelios.restlet.util.AccessLogFormatter

# The name of the character set encoding to use (defaults to the default platform encoding).
# org.restlet.engine.log.AccessLogFileHandler.encoding=

# Specifies an approximate maximum amount to write (in bytes) to any one file.
# If this is zero, then there is no limit. (Defaults to no limit).
org.restlet.engine.log.AccessLogFileHandler.limit=10000000

# Specifies how many output files to cycle through (defaults to 1).
org.restlet.engine.log.AccessLogFileHandler.count=100

# Specifies a pattern for generating the output file name. (Defaults to "%h/java%u.log").
# A pattern consists of a string that includes the following special components that will be replaced at runtime:
# "/" the local pathname separator
# "%t" the system temporary directory
# "%h" the value of the "user.home" system property
# "%g" the generation number to distinguish rotated logs
# "%u" a unique number to resolve conflicts
# "%%" translates to a single percent sign "%" .pattern=/home/prod/data/log/WebComponent-www-%u-%g.log

# Specifies whether the FileHandler should append onto any existing files (defaults to false).
# org.restlet.util.AccessLogFileHandler.append=
</pre>

=Restlet Tuning/Confguration (Jetty) as of Rifidi 3.4 (coming winter 2015)=

As of Rifidi 3.4 Jetty was made the default HTTP container for Restlet to allow for extended performance and configuration of the REST interface.

The parameters can for configured in the Rifidi Server (ini) configuration

Examples:

*-Dorg.rifidi.restlet.threadPool.minThreads=8 Thread pool minimum threads
*-Dorg.rifidi.restlet.threadPool.maxThreads=200 Thread pool max threads

Full list of Jetty parameters using the same naming convention can be found here - http://restlet.com/technical-resources/restlet-framework/javadocs/snapshot/jse/ext/org/restlet/ext/jetty/JettyServerHelper.html

=Commands=

==Command Code Snippet - start session - example how to use Rifidi API in a Java App==
All Rifidi Management API Command Logic here - https://transcends.svn.cloudforge.com/rifidi/rifidi/trunk/org.rifidi.edge/src/org/rifidi/edge/rest/SensorManagerServiceRestletImpl.java
<pre>
try {
sensorManagerService.startSession((String) request
.getAttributes().get("readerID"), (String) request
.getAttributes().get("sessionID"));
response.setEntity(self.generateReturnString(self
.generateSuccessMessage()), MediaType.TEXT_XML);
} catch (Exception e) {
response.setEntity(e.getMessage(), MediaType.TEXT_PLAIN);
}
</pre>
==Command Basic Flow Example==
#Create a Reader - http://localhost:8111/createreader/LLRP/IpAddress=127.0.0.1;Port=5084
#Create a Session (on a reader/sensor) - http://localhost:8111/createsession/LLRP_1
#Create a Command (on a reader/sensor)) -/createcommand/{commandType}/{properties}
*Note: some readers do not require create/executing a command as there is only one command hence for convenience is part of the create session/start session (Thinkify, CSL and Generic adapter (for handhelds/async push calls) are some examples of this)
#Set Command Properties - http://localhost:8111/setproperties/LLRP_Configure_1/Duration=2130
#Execute Command (on a given reader/sensor and session) - http://localhost:8111/executecommand/LLRP_1/1/LLRP_Configure_1/-1
#Start Session (to begin processing reads using associate command/reader/sensor configuration) - http://localhost:8111/startsession/LLRP_1/1
#Save Configuartion (optional - to save/persist config in case of a server restart) - http://localhost:8111/save

=Command Example=

Note: localhost can be substituted with IP address/Host name of Rifidi Edge Server. Port can be changed in Rifidi configuration

==commandtypes command example==

*commandtypes - returns a list of available command types

Request (via HTTP Post/Get) "commandtypes" command like this:

http://localhost:8111/commandtypes

Response:

<pre>
<response>
<commands>
<command>
<factoryID>LLRP-ADD_ROSPEC-File</factoryID>
<description>
Configure the LLRP reader via an XML file. Any changes made to the reader are determined by the contents of the file. To generate xml code for the commands you want to submit, check out LLRP Commander here: http://www.fosstrak.org/llrp/index.html
</description>
<readerFactoryID>LLRP</readerFactoryID>
</command>
<command>
<factoryID>ThingMagic-Poll</factoryID>
<description>
Poll the ThingMagic reader for its tags. For monitoring of the read zone, submit this command for recurring execution.
</description>
<readerFactoryID>ThingMagic</readerFactoryID>
</command>
<command>
<factoryID>Alien-Push-Start</factoryID>
<description>
Configure the Alien reader to send back tags using the autonomous mode. To monitor a read zone, configure an Alien autonomous reader to listen. Then submit this command for a one-time execution.
</description>
<readerFactoryID>Alien</readerFactoryID>
</command>
<command>
<factoryID>LLRP-Configure</factoryID>
<description>
Configure the LLRP reader to collect tags. By default, this command will cause the LLRP reader to push back tag reads automatically. If you would rather use the Poll mode, you will need to use the LLRP Poll command. To use the LLRP Configure command, submit it for a one-time execution
</description>
<readerFactoryID>LLRP</readerFactoryID>
</command>
<command>
<factoryID>LLRP-Push-Stop</factoryID>
<description>
Command the LLRP reader to stop sending back tags. To use, supply the RO Spec that is currently executing on the reader, and submit this command for a one-time execution.
</description>
<readerFactoryID>LLRP</readerFactoryID>
</command>
<command>
<factoryID>Awid2010-Poll</factoryID>
<description>
Configure the Awid reader to send back tags using the Gen 2 Portal ID command. To monitor a read zone, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid2010</readerFactoryID>
</command>
<command>
<factoryID>Thingmagic6-Push</factoryID>
<description>
Sets the Thingmagic to push tags back to the edge server
</description>
<readerFactoryID>Thingmagic6</readerFactoryID>
</command>
<command>
<factoryID>Awid3014-Poll</factoryID>
<description>
Configure the Awid reader to send back tags using the Gen 2 Portal ID command. To monitor a read zone, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid3014</readerFactoryID>
</command>
<command>
<factoryID>Awid3014-Push-Stop</factoryID>
<description>
Command the Awid reader to stop sending back tags. To use, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid3014</readerFactoryID>
</command>
<command>
<factoryID>Alien-Poll</factoryID>
<description>
Poll the Alien reader for its tag list. For monitoring of the read zone, submit this command for recurring execution.
</description>
<readerFactoryID>Alien</readerFactoryID>
</command>
<command>
<factoryID>LLRP-Poll</factoryID>
<description>
Poll the LLRP reader for its tags. For monitoring of the read zone, first use the LLRP Configure command to configure the LLRP reader for Poll Mode. Then submit this command for recurring execution.
</description>
<readerFactoryID>LLRP</readerFactoryID>
</command>
<command>
<factoryID>Awid-Mask-Poll</factoryID>
<description>
Configure the Awid reader to send back tags using the Gen 2 Portal ID With Mask command. To monitor a read zone and read a specific memory bank, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid2010</readerFactoryID>
</command>
<command>
<factoryID>Alien-Push-Stop</factoryID>
<description>
Command the Alien reader to stop sending back tags in autonomous mode. To use, submit this command for a one-time execution.
</description>
<readerFactoryID>Alien</readerFactoryID>
</command>
<command>
<factoryID>Awid2010-Push-Stop</factoryID>
<description>
Command the Awid reader to stop sending back tags. To use, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid2010</readerFactoryID>
</command>
<command>
<factoryID>Awid-Read-Block-Data</factoryID>
<description>
Configure the Awid reader to send back memory bank tags using the Read Block Data commmand. To monitor a read zone and read a specific memory bank, submit this command for a one-time execution.
</description>
<readerFactoryID>Awid2010</readerFactoryID>
</command>
</commands>
</response></pre>

==readertypes command example==

*readertypes - returns a list of available reader/sensor types (such as LLRP, Alien, BarCode etc..)

Request (via HTTP Post/Get) "readertypes" command like this:

http://localhost:8111/readertypes

Response:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sensors>
<sensor>
<factoryID>Generic</factoryID>
<description>A generic Rifidi Adapter.</description>
</sensor>
<sensor>
<factoryID>Opticon</factoryID>
<description>The Rifidi Adapter for the Opticon Barcode Sensor</description>
</sensor>
<sensor>
<factoryID>Alien-Autonomous</factoryID>
<description>The Rifidi Alien autonomous adapter is an endpoint to passively receive tag reads from an Alien reader operating in autonomous mode. You cannot send any commands on the alien autonomous session</description>
</sensor>
<sensor>
<factoryID>Awid2010</factoryID>
<description>The Rifidi Awid adapater supports the Awid TCP/IP protocol on the 2010 and 3014</description>
</sensor>
<sensor>
<factoryID>Thingmagic6</factoryID>
<description>Sensor plugin for Thingmagic 6 readers</description>
</sensor>
<sensor>
<factoryID>LLRP</factoryID>
<description>The Rifidi LLRP adapter supports any reader that exposes a Low Level Reader Protocol (LLRP) interface. LLRP is a standard from EPCglobal.</description>
</sensor>
<sensor>
<factoryID>Awid3014</factoryID>
<description>The Rifidi Awid adapater supports the Awid TCP/IP protocol on the 2010 and 3014</description>
</sensor>
<sensor>
<factoryID>Alien</factoryID>
<description>The Rifidi Alien adapter supports the Alien ALR protocol on the 9900, 9800, 8800 readers.</description>
</sensor>
<sensor>
<factoryID>Thinkify50</factoryID>
<description>Sensor plugin for Thinkify TR50 readers</description>
</sensor>
<sensor>
<factoryID>ThingMagic</factoryID>
<description>The Rifidi ThingMagic adapater supports the ThingMagic RQL protocol on the Mercury 4 and Mercury 5 readers</description>
</sensor>
</sensors>
</response>
</pre>

==createreader command example==

Note: The command is atomic so either all the parameters/properties in request are valid hence the reader/sensor adapter instance is created or the call fails therefore the reader/adapter instance is not created

*createreader/{readerType}/{properties} -creates a reader/sensor configuration

*Special characters: See how to send special characters in properties' values http://wiki.rifidi.net/index.php?title=Rifidi_App_API#Properties_with_special_characters

Request (via HTTP Post/Get) "createreader" command like this (splitting all property key/value pairs by a semicolon):

Response success:

http://localhost:8111/createreader/LLRP/IpAddress=127.0.0.1;Port=5084

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<readerID>LLRP_1</readerID> Note: added in in 4.0 release
<message>Success</message>
</response>
</pre>

Response fail (if there is at least one non valid property, the reader is not created):

http://localhost:8111/createreader/LLRP/IpAddress=127.0.0.2;Port=5084;fakeProp=1234;anotherProp=ABC

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Fail</message>
<description>Not valid properties: fakeProp=1234|anotherProp=ABC</description>
</response>
</pre>

==createreader overriding default readerID command example==

The reader id is important for applications' read zones to appropriate operate, and this id is used to link read zones with sensors. This command enables one to set the readerId versus the system generating one (default behavior).

Note: To override the default reader id, there must be included the property readerID, in order to assign a specific reader id and override the default.
Note: The command is atomic so either all the parameters/properties in request are valid hence the reader/sensor adapter instance is created or the call fails therefore the reader/adapter instance is not created

*createreader/{readerType}/{properties} -creates a reader/sensor configuration

*Special characters: See how to send special characters in properties' values http://wiki.rifidi.net/index.php?title=Rifidi_App_API#Properties_with_special_characters

Request (via HTTP Post/Get) "createreader" command like this (splitting all property key/value pairs by a semicolon):

Response success:

http://localhost:8111/createreader/LLRP/IpAddress=127.0.0.1;Port=5084;readerID=myReaderID

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<readerID>LLRP_1</readerID> Note: added in in 4.0 release
<message>Success</message>
</response>
</pre>

Response fail (if there is at least one non valid property, the reader is not created):

http://localhost:8111/createreader/LLRP/IpAddress=127.0.0.2;Port=5084;fakeProp=1234;anotherProp=ABC;readerID=myReaderID

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Fail</message>
<description>Not valid properties: fakeProp=1234|anotherProp=ABC</description>
</response>
</pre>

==deletereader command example (released in 3.2)==

Note: The command is atomic so either all the parameters/properties in request are valid hence the reader/sensor adapter instance is created or the call fails therefore the reader/adapter instance is not created

*deletereader/{readerID} -deletes a reader/sensor configuration

Response success:

http://localhost:8111/deletereader/LLRP_1

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

Response fail (if there is at least one non valid property, the reader is not created):

http://localhost:8111/deletereader/LLRP

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Fail</message>
<description>Not valid readerID: LLRP</description>
</response>
</pre>

==readers command example==

Request (via HTTP Post/Get) "readers" command like this:

*readers - returns a list of readers/senors managed by the Edge Server

http://localhost:8111/readers

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sensors>
<sensor>
<serviceID>Alien_1</serviceID>
<factoryID>Alien</factoryID>
</sensor>
<sensor>
<serviceID>Alien_2</serviceID>
<factoryID>Alien</factoryID>
</sensor>
</sensors>
</response>
</pre>

==getproperties command example (to get reader properties)==

*getproperties/{readerID} - returns the reader/sensor properties

Request (via HTTP Post/Get) "getproperties" command like this, to get a reader properties:

http://localhost:8111/getproperties/LLRP_1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<attributes>
<entry>
<key>ReconnectionInterval</key>
<value>500</value>
</entry>
<entry>
<key>Port</key>
<value>5084</value>
</entry>
<entry>
<key>IpAddress</key>
<value>192.168.1.48</value>
</entry>
<entry>
<key>MaxNumConnectionAttempts</key>
<value>10</value>
</entry>
<entry>
<key>DisplayName</key>
<value>null</value>
</entry>
<entry>
<key>ReaderConfigPath</key>
<value>config/SET_READER_CONFIG.llrp</value>
</entry>
</attributes>
</response>
</pre>

==getproperties command example (to get command properties)==

*getproperties/{commandID} - returns the command properties

Request (via HTTP Post/Get) "getproperties" command like this:

http://localhost:8111/getproperties/LLRP_Configure_1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<attributes>
<entry>
<key>ROSpecID</key>
<value>1</value>
</entry>
<entry>
<key>AntennaIDs</key>
<value>0</value>
</entry>
<entry>
<key>Duration</key>
<value>1000</value>
</entry>
<entry>
<key>TriggerType</key>
<value>PUSH</value>
</entry>
</attributes>
</response>
</pre>

==setproperties command example (to set reader properties)==

*setproperties/{readerID}/{properties}" - sets the reader/sensor properties
Note: if there is an existing session for updated reader properties to take effect the session will need to be deleted and recreated so the properties are moved to the session

*Special characters: See how to send special characters in properties' values http://wiki.rifidi.net/index.php?title=Rifidi_App_API#Properties_with_special_characters

Request (via HTTP Post/Get) setproperties" like this (splitting all property key/value pairs by a semicolon):

Response success:

http://localhost:8111/setproperties/Alien_1/MaxNumConnectionAttempts=11;DisplayName=Alien_Name

<pre>
<response><message>Success</message></response>
</pre>

Response fail (valid properties are set, ignoring not valid ones):

http://localhost:8111/setproperties/LLRP_1/IpAddress=127.0.0.15;Port=4567;att1=aa;att2=bbb;attt3=YY

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
<state>Warning</state>
<description>Not valid properties: att1=aa|att2=bbb|attt3=YY</description>
</response>
</pre>

==setproperties command example (to set command properties)==

*setproperties/{commandID}/{properties}" - sets the command properties

*Special characters: See how to send special characters in properties' values http://wiki.rifidi.net/index.php?title=Rifidi_App_API#Properties_with_special_characters

Request (via HTTP Post/Get) setproperties" like this (splitting all property key/value pairs by a semicolon):

Response success

http://localhost:8111/setproperties/LLRP_Configure_1/Duration=2130

<pre>

<response><message>Success</message></response>
</pre>

Response fail (valid properties are set, ignoring not valid ones):

http://localhost:8111/setproperties/LLRP_Configure_1/Duration=7500;cc=4;other=67

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
<state>Warning</state>
<description>Not valid properties: cc=4|other=67</description>
</response>
</pre>

==commands command example==

*commands - returns a list of available commands

Request (via HTTP Post/Get) "commands" command like this:

http://localhost:8111/commands

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<commands>
<command>
<commandID>LLRP_Configure_1</commandID>
<factoryID>LLRP-Configure</factoryID>
</command>
</commands>
</response>
</pre>

==createcommand example==

Note: The command is atomic so either all the parameters/properties in request are valid hence the command instance is created or the call fails therefore the rcommand instance is not created

*createcomamnd/{commandType}/{properties} - creates a command to be executed on a reader session

*Special characters: See how to send special characters in properties' values http://wiki.rifidi.net/index.php?title=Rifidi_App_API#Properties_with_special_characters

Request (via HTTP Post/Get) "createcommand" command like this (splitting all property key/value pairs by a semicolon):

Response success:

http://localhost:8111/createcommand/LLRP-Configure/Duration=5000

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<commandID>Alien_Poll_2</commandID> Note: Added in 4.0 release
<message>Success</message>
</response>
</pre>

Response error (if there is at least one non valid property, the command is not created):

http://localhost:8111/createcommand/LLRP-Configure/Duration=4000;propX=123;prop2=AB

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Fail</message>
<description>Not valid properties: propX=123|prop2=AB</description>
</response>
</pre>

==deletecommand command example (released in 3.2)==

Note: The command is atomic so either all the parameters/properties in request are valid hence the reader/sensor adapter instance is created or the call fails therefore the reader/adapter instance is not created

*deletecommand/{commandID} -deletes a reader/sensor configuration

Response success:

http://localhost:8111/deletecommand/LLRP_Configure_1

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

Response fail (if there is at least one non valid property, the reader is not created):

http://localhost:8111/deletecommand/LLRP_Configure

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Fail</message>
<description>Not valid commandID: LLRP_Configure</description>
</response>
</pre>

==createsession command example==

*createsession/{readerID} - creates a session (with corresponding reader/sensor configuration) and returns status code (such as successful)

Request (via HTTP Post/Get) "createsession" command like this:

http://localhost:8111/createsession/LLRP_1

Response: Success
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sessionID>1</sessionID>
<message>Success</message>
</response>
</pre>

Response: Fail -already a session for sensor id
<pre>
<?xml version="1.0" encoding="UTF-8"?>

<response>
<message>Fail</message>
<description>
java.lang.Exception: Reader Alien_1 already has a session.
</description>
</response>
</pre>

==startsession command example==

*startsession/{readerID}/{sessionID} - starts a session for a given reader/sensor and returns status code (such as successful)

Request (via HTTP Post/Get) "startsession" command like this:

http://localhost:8111/startsession/LLRP_1/1

Response: Success
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

Response: Fail
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Error</message>
<state>CONNECTING</state>
<description>Unable to start session, current state is CONNECTING - See Rifidi Edge Sever Log for details</description>
</response>
</pre>

==readerstatus command example==

*readerstatus/{readerID} - retuns teh status of a given reader/sensor

Request (via HTTP Post/Get) "readerstatus" command like this:

http://localhost:8111/readerstatus/LLRP_1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sensor>
<serviceID>LLRP_1</serviceID>
<factoryID>LLRP</factoryID>
</sensor>
<sessions>
<session>
<ID>1</ID>
<status>PROCESSING</status>

<executingcommands>
<executingcommand>
<commandFactory>LLRP-Configure</commandFactory>
<commandID>LLRP_Configure_1</commandID>
<interval>0</interval>
</executingcommand>
</executingcommands>
</session>
</sessions>
</response>
</pre>

==stopsession command example==

*stopsession/{readerID}/{sessionID} - stops a session for a given reader/sensor and returns status code (such as successful)

Request (via HTTP Post/Get) "stopsession" command like this:

http://localhost:8111/stopsession/LLRP_1/1

Response success:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

Response fail:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Error</message>
<state>CREATED</state>
<description>Unable to stop session, current state is CREATED - See Rifidi Edge Sever Log for details</description>
</response>
</pre>

==executecommand command example==

*executecommand/{readerID}/{sessionID}/{commandID}/{repeatInterval} - Executes a command for a given session

Request (via HTTP Post/Get) "executecommand" command like this:

http://localhost:8111/executecommand/LLRP_1/1/LLRP_Configure_1/-1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

==deletesession command example==

*deletesession/{readerID}/{sessionID} - deletes a session and returns status code (such as successful)

Request (via HTTP Post/Get) "deletesession" command like this:

http://localhost:8111/deletesession/LLRP_1/1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

==save command example==

*save - Saves the current state of the Edge Server configuration (such as created readers/sensors, modified properties etc..

Request (via HTTP Post/Get) "save" command like this:

http://localhost:8111/save

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<message>Success</message>
</response>
</pre>

==Ping - Used by failover feature==
*ping - Returns a date/timestamp

Request (via HTTP Post/Get) "ping" command like this:

http://localhost:8111/ping

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<timestamp>1414610247969</timestamp>
</response>
</pre>

==currenttags example (to be released in Rifidi 3.4 targeting Winter 2015==
*currenttags/{readerID} - Returns a list of tags on a given reader

Request (via HTTP Post/Get) "currenttags" command like this:

http://localhost:8111/currenttags/LLRP_1

Response:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<currenttags>
<tag>3088F9F16B1C87544D54DD07</tag>
<tag>30615D9FE491056264DC8A79</tag>
<tag>30E8AF452F8DD97AD0A59B9F</tag>
<tag>30A90E7816B03459349C6386</tag>
</currenttags>
</response>
</pre>

==readermetadata - Used by Web Administration Dashboard for Dynamic Reader & Command Properties/Wizard (released in 3.2)==
*readermetadata- Returns reader metadata

Request (via HTTP Post/Get) "readermetadata" command like this:

http://localhost:8111/readermetadata

Response:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><response>
<response>
<readers>
<reader>
<properties>
<property>
<name>ReconnectionInterval</name>
<displayName>Reconnection Interval</displayName>
<defaultvalue>500</defaultvalue>
<description>
Upon connection failure, the time to wait between two connection attempts (ms)
</description>
<type>java.lang.Integer</type>
<minvalue>0</minvalue>
<category>connection</category>
<writable>true</writable>
<ordervalue>4.0</ordervalue>
</property>
<property>
<name>Port</name>
<displayName>Port</displayName>
<defaultvalue>8090</defaultvalue>
<description>Port of the Reader</description>
<type>java.lang.Integer</type>
<maxvalue>65535</maxvalue>
<minvalue>0</minvalue>
<category>connection</category>
<writable>true</writable>
<ordervalue>1.0</ordervalue>
</property>
</pre>

TagStreamerSpecification

2015-07-28T18:37:54Z

Nurban:

==Introduction==

This document describes a possible use case for TagStreamer 2.0 for the purpose of demonstrating how it would work. The basic idea is to define a Scenario that describes the flow of input data through processing points and BatchPattern which describe the input data in general. The processing points of the Scenario are called path items. They consist of either a reader or a GPI Listener and a time to wait before moving on to the next path item. It is important to note that the scenario and the data are decoupled. The BatchPattern describes the speed which data will put into the Scenario and how many tags will be generated. The Tag Generator uses that information and executes the BatchPattern one activated.

In the below scenario, a batch item – a group of tags – moves into the entry point of the scenario by being processed by reader 1. Reader 1 adds the tags to its antenna for a variable amount of time, between 4 and 8 seconds. Then the tags wait for 5 seconds before moving on to the next path item.

The next path item is a GPI Listener that is tied to Reader 2. Because this particular Batch Item is set to trigger GPI Listeners, the GPI Listener will toggle one of Reader 2's GPI ports. The batch item now waits for 5 more seconds. Now the tags in the batch are seen by reader 2's antenna for 3 seconds and then wait for anywhere between 10 and 20 seconds before moving on to Reader 3.

Once the tags are seen by reader 3, this iteration of the scenario is over. The TagGenerator can execute a BatchPattern more than once. This will be defined as the iteration of the BatchPattern.

[[Image:TagStreamerSpec.png]]

==Components==
A TagStreamer usecase consists of two main components -- the Scenario and the Input Data. Both are decoupled so that neither depends on the other part.

# Scenario - The Scenario describes the path through which a tag batch flows. It is made up of path items. It also contains a variable that controls how many times the scenario is repeated. If the variable is 0, the scenario is run infinitely. If it is positive, it is run n times.
## PathItem - A path item consists of either a reader or a GPI Listener and a time to wait.
###Reader - An RFID reader which tags appear on
###GPI Listener - If a Batch Item which is set to trigger a GPI event passes through a GPI Listener, it will trigger a GPI event on the GPI Listener's reader.
###Time - A time is used either to describe the amount of time that a batch item should wait on a Path Item, or the amount of time a batch item should wait after being processed by the path item. For example, in the above use case, if the tag batch moved to reader 1, it is processed by the reader for 4-8 seconds (i.e. It is added to the reader's antenna for this amount of time). Then it waits for 5 seconds before it proceeds to the next path item. It can be a random amount of time with a min value and a max value. If it's not a random value both values should be equal.
#BatchPattern - A way to describe BathItems generated at the runtime. Each batch items flows through the Scenario by starting at the entry point and being processed sequentially at each Path Item.
##BatchItem - A batch item contains a list of tags, a boolean that describes whether or not it should trigger GPI Listeners and a time value that describes the amount of time it should wait before being processed by the first path item.
### GPI Trigger - A boolean value that defines whether or not the asociated batch item should cause GPI Listerns to fire a GPI event.
### Tags - A list of RFID tags to be added to readers. They are defined by an ID, a Generation( Gen1 or Gen2), and type (e.g. DOD-96).

==XML==
===Scenario.xml===
This XML describes the PathItems and the way Data moves through the scenario to the various components like RFID Readers & GPI Listeners.
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<scenario id="0">
<pathItem id="0">
<readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
<readerID>0</readerID>
</readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
</pathItem>
<pathItem id="1">
<gpiListenerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
<gpiListenerID>0</gpiListenerID>
</gpiListenerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
</pathItem>
<pathItem id="2">
<readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
<readerID>0</readerID>
</readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
</pathItem>
<pathItem id="3">
<readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
<readerID>0</readerID>
</readerEntity>
<timeEntity>
<random>true</random>
<minValue>400</minValue>
<maxValue>500</maxValue>
</timeEntity>
</pathItem>
</scenario>
</pre>

===Component.xml===
This XML describes the various components (ie RFID Readers & GPI Listeners) in the scenario

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<componentList id="0">
<readerComponents id="0">
<reader>
<numAntennas>1</numAntennas>
<numGPIs>4</numGPIs>
<numGPOs>4</numGPOs>
<propertiesMap>
<entry>
<key>servermode</key>
<value>true</value>
</entry>
<entry>
<key>inet_address</key>
<value>127.0.0.1:10101</value>
</entry>
<entry>
<key>llrp_inet_address</key>
<value>127.0.0.1:5084</value>
</entry>
</propertiesMap>
<readerClassName>org.rifidi.emulator.reader.llrp.module.LLRPReaderModule</readerClassName>
<readerName>LLRPreader</readerName>
<readerType>LLRPReader</readerType>
</reader>
</readerComponents>
<readerComponents id="1">
<reader>
<numAntennas>1</numAntennas>
<numGPIs>4</numGPIs>
<numGPOs>4</numGPOs>
<propertiesMap>
<entry>
<key>servermode</key>
<value>true</value>
</entry>
<entry>
<key>inet_address</key>
<value>127.0.0.1:10102</value>
</entry>
<entry>
<key>llrp_inet_address</key>
<value>127.0.0.1:5085</value>
</entry>
</propertiesMap>
<readerClassName>org.rifidi.emulator.reader.llrp.module.LLRPReaderModule</readerClassName>
<readerName>LLRPreader2</readerName>
<readerType>LLRPReader</readerType>
</reader>
</readerComponents>
<gpiListenerComponents id="0">
<port>0</port>
<readerID>0</readerID>
<signalValue>true</signalValue>
</gpiListenerComponents>
</componentList>
</pre>

===BatchPattern.xml===
The BatchPattern describes the input data generated at the runtime by the BatchGenerators. This will create BatchItems wich certain tags and flow through the scenario.
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batchPattern id="1">
<scenario>3</scenario>
<interation>250</iteration>
<burstNumber>50</busrtNumber>
<burstInterval>4000</burstInterval>
<isGPITrigger>true</isGPITrigger>
<tagPattern count="100">
<type>Custom</type>
<prefix>eef</prefix>
<gen>2</gen>
</tagPattern>
<tagPattern count="90">
<type>DOD</type>
</prefix>
<gen>2</gen>
</tagPattern>
</batchPattern>
</pre>

How to Contribute to the Rifidi project

2015-01-30T21:46:05Z

Nurban:

The Rifidi Edge Server is open source. This means that if you find bugs or have ideas for useful features, you have the ability to extend the edge server yourself! We will gladly welcome contributions of any sort (code, documentation, testing, etc) and encourage you to submit these back. To get involved with the community:
# '''Visit''' our [http://forums.rifidi.net forums]. This is the best place to talk to our developers and users of Rifidi.
# '''Submit''' feature requests and bug reports. We have a [http://forums.rifidi.net bug tracking system] that manages outstanding feature requests and bugs. Before you submit bug reports here, we ask that you visit us on the forums first and make sure that there isn't a known solution for your question already
# '''Contribute''' to our wiki. We gladly welcome any documentation in the form of HOWTOs, example code, tutorials, or any other form that you find helpful.

For more information, please send emails to support@transcends.co

Rifidi:Source Code

2015-01-07T22:19:30Z

Nurban: /* Organization */

[[category:developerDoc]]
This page explains how to download and run the source code for the Rifidi products. However, please keep in mind that the code in this repository is not guaranteed to be stable. If you are interested in our latest stable release, visit our sourceforge page: http://sourceforge.net/projects/rifidi/.
=Quick Instructions=
The following are the basic steps needed to begin running Rifidi from source. If you have trouble or need more explanation, please see the more detailed instructions on this page.
# Download the Eclipse for plugin developers (3.5 is what we are using)
# Install the subclipse plugin
# Add this svn to the list of repositories: emulator, prototyper - https://transcends.svn.cloudforge.com/emulator, edge, workbench - https://transcends.svn.cloudforge.com/rifidi
# Check out the following projects from rifidi/trunk: org.rifidi.binary, org.rifidi.emulator.target, org.rifidi.ui.ide
# Open up the target file in org.rifidi.emulator.target and click the button that says "set as target platform"
# Open up the .product file in org.rifidi.ui.ide and click "launch an eclipse application"

=Rifidi Source Code=
For those who need to see the source code for the Rifidi products, you will have to check out the code from svn. This section explains how to check out and run the code from source.
==Organization==
In general the code for Rifidi is organized into Eclipse plugins or bundles. Eclipse handles the loading and execution of the plugins. For more detailed information about how our source code is organized, please see [[Development and Release Process#Concepts]].
* '''SVN Structure''' - There are three main folders in the Rifidi directory on <code>rep-external</code> (the main svn repository for Rifidi). The ''trunk'' folder contains the code that is being developed. It is ''not'' guaranteed to be stable. The ''tags'' folder contains tagged versions of the source for each of the plugins. The source in these plugins should be relatively stable. The ''branches'' folder contains plugins that have been branched so that larger changes can be made on plugins without holding up other developers. These changes can then later be merged back in. For more details about our SVN, see [[Development and Release Process#SVN Structure]]
* Target Platform - A target platform is the base set of plugins that an Eclipse application needs to run. In order to provide a more stable environment and to ensure a clean separation between the base plugins that Rifidi needs and the base plugins that your Eclipse IDE needs, we provide a target platform for each of the Rifidi products. You can find these in the trunk. They will be named something like <code>org.rifidi.emulator.target</code>. For more information see [[Development and Release Process#Target Platforms]].
* org.rifidi.binary - As the source code for Rifidi gets larger it begins to get harder to maintain a stable set of plugins. In order to simplify things, there is a folder in the svn into which stable binaries of each of the plugins used in the rifidi project will be placed. This folder is used in conjunction with the target platform.
* Product File - In Eclipse, a product file is used to define the needed eclipse plugins. Running this file will create a new Eclipse 'Run Configuration' in your IDE. You can then tweak this run configuration as needed.
* Source Code Plugins - A stable binary version of each of the plugins is contained in the org.rifidi.binary folder. However, if you wish to view the source of a particular plugin or run a plugin from source, you must download the code from either the version in the trunk or a tagged version in the tags directory.

==Downloading the Code==

Our code is hosted at https://transcends.svn.cloudforge.com/rifidi and https://transcends.svn.cloudforge.com/emulator. The svn repository allows anonymous read access. Because the svn repository is the same one that developers submit to, it contains the latest Rifidi code.

The following steps explain how to check out and run Rifidi Emulator. The other products in the Rifidi Suite follow similar steps. If you need help with them, you can ask questions on IRC or our forums.

===Prerequisites===

The Rifidi Emulator is written in java and consists of Eclipse plugins. At this point it is easiest to compile and build it inside of the eclipse environment.

====Install Eclipse====
Note that you need the "Eclipse for RCP/Plug-in Developers" version of eclipse. Rifidi will not run on other versions.
* If you do not already have eclipse, or if you have a different version, you will need to get this version
** Go to http://www.eclipse.org/downloads/ and download the "Eclipse for RCP/Plug-in Developers" version of Eclipse to a convenient location.
** Unzip the package.
** Double click on the execution file to get it started [[Image:Rifidi_from_source-1-opening_eclipse.png |none|thumb|800px|Double click on the executable to open up eclipse]]
* If you have not used eclipse before, you will be required to select a workspace when eclipse is opening.
** After eclipse opens go to the workbench[[Image:Rifidi_from_source-2-wokbench.png |none|thumb|800px|Open up the workbench]]
* If you have an existing workspace, you will need to create a new one.
** Go to file -> switch workspace -> other [[Image:Rifidi_from_source-3-switch_workspace.png |none|thumb|800px|Open up the workbench]]
** Select a new directory for your Rifidi workspace.

====Install Subclipse====

Subclipse is an eclipse plugin that manages svn commands.

* Follow the instructions at http://subclipse.tigris.org/install.html.
* In step 6 of the above instructions, don't install the Optional Integrations. Only the subclipse plugin is needed

===Add Repository===

* Open the 'SVN Repository Exploring' perspective
** Window -> Open Perspective -> Other [[Image:Rifidi_from_source-4-svn_rep_explore1.png |none|thumb|800px|Open up the perspective picker]]
** SVN Repository Exploring [[Image:Rifidi_from_source-5-svn_rep_explore2.png |none|thumb|400px|Open up the SVN Repository Explorer]]
* Add the rifidi repository
** Click 'Add SVN Repository' button
** Add ' https://transcends.svn.cloudforge.com/rifidi '[[Image:Rifidi_from_source-6-add_rep.png |none|400px|thumb|Add the repository]]

===Check Out Code===

* Check out all the projects in the rifidi/trunk folder of the repository
** Highlight the folders you would like to check out. For Emulator you will need
*** <code>org.rifidi.binary</code>
*** <code>org.rifidi.emulator.taget3.5.2</code>
*** <code>org.rifidi.ui.ide</code>
** Right click them and select checkout [[Image:Rifidi_from_source-7-checkout1.png |none|800px|thumb|Select the projects]]
** Select Finish. [[Image:Rifidi_from_source-8-checkout2.png |none|400px|thumb|Checkout projects]]

===Set The Target Platform===
* Open up the .target file in <code>org.rifidi.emulator.target</code>
* Click the button that says "set as target platform"

==Running Rifidi==

The last step to get Rifidi running is to create a run configuration.

A run configuration is the set of plugins that will be loaded when you run the application. Plugins can come from one of two places:
#Workspace - these are the plugins that you have in the source tree on the left
#Target Environment - These are the plugins defined by the target environment that you are using that the time.

Because there is a product file for emulator defined in the <code>org.rifidi.ui.ide</code> plugin, the easiest way to create a new run configuration is by running the product file. This will automatically create a new run configuration

To Create a new Run Configuration:
* Switch to the Java perspective in the same way that you switched to the repository exploring view [[Image:Rifidi_from_source-9-java_view.png |none|400px|thumb|Run Rifidi]]
* Right click on Rifidi.product in the org.rifidi.ui.ide project
* Click on "Run as eclipse application" [[Image:Rifidi_from_source-10_run_eclipse.png |none|thumb|800px|Run Rifidi]]
* From now on, you can start Rifidi via the green triangle button at the top of eclipse

If there was an error when starting the application, follow the step below to edit the run configuration:

To Edit a Run Configuration:
* Run -> Open Run Dialog -> Eclipse Application -> Rifidi.product. This is the run configuration.
* Go to the Tab Plug-ins. The selected plugins are the ones that will be run. Notice that there are two sections: "workspace" and "target platform"
* click the Button "Add Required Plug-ins" [[Image:Rifidi_from_source-11_add_plugins.png |none|thumb|600px|Add required plugins]]
* check any plugins specifically required for the application to run (for example, the emulator requires the readers to be included). Make sure that the plugin is coming from the place [http://www.miiny.com deals singapore] that you intended (i.e. workspace or target platform).
* click the Button "Validate Plug-ins" to make sure everything is set up correctly
* click the Button "Apply"
* click the Button "Run" and start the Project

==Updating the code==

Now that you have downloaded the code into an eclipse workspace, it is easy to get changes to the code as soon as we add them to the svn.

To update the code:

* Open up the Team Synchronizing Perspective in eclipse
* Click the button that says "Synchronize".
* Select all projects.
* Install any updates by selecting all the updates show, right clicking and choosing 'update'

Now that you have the new code, just hit the green run button on the toolbar at the top (Eclipse automatically compiles the code for you, so you don't have to worry about that).

==Switching Branches==
If you need to run code from another branch or tag, please see [[Switching Branches]].

==Viewing Source and Running From Trunk==
By default all of the rifidi plugins you are running in eclipse are pre-compiled, binary plugins contained in the <code>org.rifidi.binary</code> folder. If you want to view or edit the source for a particular plugin, you will need to check out the plugin from the trunk. Once it is checked out make sure to edit your run configuration so that the application will use the plugin from the workspace and not from the target platform.

For example, suppose I want to view the source for the Alien reader plugin. I need to follow the steps above to check out and run rifidi emulator. In addition, I need to check out the <code>org.rifidi.emulator.readers.alien</code> plugin. This is the code for the alien reader. In addition, I need to edit the run configuration to make sure that my workspace alien reader plugin is being used instead of the target platform alien reader plugin.

=Reporting Bugs=

To report bugs, please use the forum at

http://forums.rifidi.net

or drop by our IRC channel:

<nowiki>#rifidi on irc.freenode.org.</nowiki>

You can also visit us online at http://www.rifidi.net

Rifidi:Source Code

2015-01-07T22:17:13Z

Nurban: /* Organization */

[[category:developerDoc]]
This page explains how to download and run the source code for the Rifidi products. However, please keep in mind that the code in this repository is not guaranteed to be stable. If you are interested in our latest stable release, visit our sourceforge page: http://sourceforge.net/projects/rifidi/.
=Quick Instructions=
The following are the basic steps needed to begin running Rifidi from source. If you have trouble or need more explanation, please see the more detailed instructions on this page.
# Download the Eclipse for plugin developers (3.5 is what we are using)
# Install the subclipse plugin
# Add this svn to the list of repositories: emulator, prototyper - https://transcends.svn.cloudforge.com/emulator, edge, workbench - https://transcends.svn.cloudforge.com/rifidi
# Check out the following projects from rifidi/trunk: org.rifidi.binary, org.rifidi.emulator.target, org.rifidi.ui.ide
# Open up the target file in org.rifidi.emulator.target and click the button that says "set as target platform"
# Open up the .product file in org.rifidi.ui.ide and click "launch an eclipse application"

=Rifidi Source Code=
For those who need to see the source code for the Rifidi products, you will have to check out the code from svn. This section explains how to check out and run the code from source.
==Organization==
In general the code for Rifidi is organized into Eclipse plugins or bundles. Eclipse handles the loading and execution of the plugins. For more detailed information about how our source code is organized, please see [[Development and Release Process#Concepts]].
* '''SVN Structure''' - There are three main folders in the Rifidi directory on <code>rep-external</code> (the main svn repository for Rifidi). The ''trunk'' folder contains the code that is being developed. It is ''not'' guaranteed to be stable. The ''tags'' folder contains tagged versions of the source for each of the plugins. The source in these plugins should be relatively stable. The ''branches'' folder contains plugins that have been branched so that larger changes can be made on plugins without holding up other developers. These changes can then later be merged back in. For more details about our SVN, see [[Development and Release Process#SVN Structure]]
* Target Platform - A target platform is the base set of [http://www.timewing.com.sg/ac_service.html ac repair] plugins that an Eclipse application needs to run. In order to provide a more stable environment and to ensure a clean separation between the base plugins that Rifidi needs and the base plugins that your Eclipse IDE needs, we provide a target platform for each of the Rifidi products. You can find these in the trunk. They will be named something like <code>org.rifidi.emulator.target</code>. For more information see [[Development and Release Process#Target Platforms]].
* org.rifidi.binary - As the source code for Rifidi gets larger it begins to get harder to maintain a stable set of plugins. In order to simplify things, there is a folder in the [http://www.timewing.com.sg/refrg_service.html refrigerator repair] svn into which stable binaries of each of the plugins used in the rifidi project will be placed. This folder is used in conjunction with the target platform.
* Product File - In Eclipse, a product file is used to define the needed eclipse plugins. Running this file will create a new Eclipse 'Run Configuration' in your IDE. You can then tweak this run configuration as needed.
* Source Code Plugins - A stable binary version of each of the plugins is [http://jamumassagesingapore.com/services/dejamu/post-natal jamu postnatal massage] contained in the org.rifidi.binary folder. However, if you wish to view the source of a particular plugin or run a plugin from source, you must download the code from either the version in the trunk or a tagged version in the tags directory.

==Downloading the Code==

Our code is hosted at https://transcends.svn.cloudforge.com/rifidi and https://transcends.svn.cloudforge.com/emulator. The svn repository allows anonymous read access. Because the svn repository is the same one that developers submit to, it contains the latest Rifidi code.

The following steps explain how to check out and run Rifidi Emulator. The other products in the Rifidi Suite follow similar steps. If you need help with them, you can ask questions on IRC or our forums.

===Prerequisites===

The Rifidi Emulator is written in java and consists of Eclipse plugins. At this point it is easiest to compile and build it inside of the eclipse environment.

====Install Eclipse====
Note that you need the "Eclipse for RCP/Plug-in Developers" version of eclipse. Rifidi will not run on other versions.
* If you do not already have eclipse, or if you have a different version, you will need to get this version
** Go to http://www.eclipse.org/downloads/ and download the "Eclipse for RCP/Plug-in Developers" version of Eclipse to a convenient location.
** Unzip the package.
** Double click on the execution file to get it started [[Image:Rifidi_from_source-1-opening_eclipse.png |none|thumb|800px|Double click on the executable to open up eclipse]]
* If you have not used eclipse before, you will be required to select a workspace when eclipse is opening.
** After eclipse opens go to the workbench[[Image:Rifidi_from_source-2-wokbench.png |none|thumb|800px|Open up the workbench]]
* If you have an existing workspace, you will need to create a new one.
** Go to file -> switch workspace -> other [[Image:Rifidi_from_source-3-switch_workspace.png |none|thumb|800px|Open up the workbench]]
** Select a new directory for your Rifidi workspace.

====Install Subclipse====

Subclipse is an eclipse plugin that manages svn commands.

* Follow the instructions at http://subclipse.tigris.org/install.html.
* In step 6 of the above instructions, don't install the Optional Integrations. Only the subclipse plugin is needed

===Add Repository===

* Open the 'SVN Repository Exploring' perspective
** Window -> Open Perspective -> Other [[Image:Rifidi_from_source-4-svn_rep_explore1.png |none|thumb|800px|Open up the perspective picker]]
** SVN Repository Exploring [[Image:Rifidi_from_source-5-svn_rep_explore2.png |none|thumb|400px|Open up the SVN Repository Explorer]]
* Add the rifidi repository
** Click 'Add SVN Repository' button
** Add ' https://transcends.svn.cloudforge.com/rifidi '[[Image:Rifidi_from_source-6-add_rep.png |none|400px|thumb|Add the repository]]

===Check Out Code===

* Check out all the projects in the rifidi/trunk folder of the repository
** Highlight the folders you would like to check out. For Emulator you will need
*** <code>org.rifidi.binary</code>
*** <code>org.rifidi.emulator.taget3.5.2</code>
*** <code>org.rifidi.ui.ide</code>
** Right click them and select checkout [[Image:Rifidi_from_source-7-checkout1.png |none|800px|thumb|Select the projects]]
** Select Finish. [[Image:Rifidi_from_source-8-checkout2.png |none|400px|thumb|Checkout projects]]

===Set The Target Platform===
* Open up the .target file in <code>org.rifidi.emulator.target</code>
* Click the button that says "set as target platform"

==Running Rifidi==

The last step to get Rifidi running is to create a run configuration.

A run configuration is the set of plugins that will be loaded when you run the application. Plugins can come from one of two places:
#Workspace - these are the plugins that you have in the source tree on the left
#Target Environment - These are the plugins defined by the target environment that you are using that the time.

Because there is a product file for emulator defined in the <code>org.rifidi.ui.ide</code> plugin, the easiest way to create a new run configuration is by running the product file. This will automatically create a new run configuration

To Create a new Run Configuration:
* Switch to the Java perspective in the same way that you switched to the repository exploring view [[Image:Rifidi_from_source-9-java_view.png |none|400px|thumb|Run Rifidi]]
* Right click on Rifidi.product in the org.rifidi.ui.ide project
* Click on "Run as eclipse application" [[Image:Rifidi_from_source-10_run_eclipse.png |none|thumb|800px|Run Rifidi]]
* From now on, you can start Rifidi via the green triangle button at the top of eclipse

If there was an error when starting the application, follow the step below to edit the run configuration:

To Edit a Run Configuration:
* Run -> Open Run Dialog -> Eclipse Application -> Rifidi.product. This is the run configuration.
* Go to the Tab Plug-ins. The selected plugins are the ones that will be run. Notice that there are two sections: "workspace" and "target platform"
* click the Button "Add Required Plug-ins" [[Image:Rifidi_from_source-11_add_plugins.png |none|thumb|600px|Add required plugins]]
* check any plugins specifically required for the application to run (for example, the emulator requires the readers to be included). Make sure that the plugin is coming from the place [http://www.miiny.com deals singapore] that you intended (i.e. workspace or target platform).
* click the Button "Validate Plug-ins" to make sure everything is set up correctly
* click the Button "Apply"
* click the Button "Run" and start the Project

==Updating the code==

Now that you have downloaded the code into an eclipse workspace, it is easy to get changes to the code as soon as we add them to the svn.

To update the code:

* Open up the Team Synchronizing Perspective in eclipse
* Click the button that says "Synchronize".
* Select all projects.
* Install any updates by selecting all the updates show, right clicking and choosing 'update'

Now that you have the new code, just hit the green run button on the toolbar at the top (Eclipse automatically compiles the code for you, so you don't have to worry about that).

==Switching Branches==
If you need to run code from another branch or tag, please see [[Switching Branches]].

==Viewing Source and Running From Trunk==
By default all of the rifidi plugins you are running in eclipse are pre-compiled, binary plugins contained in the <code>org.rifidi.binary</code> folder. If you want to view or edit the source for a particular plugin, you will need to check out the plugin from the trunk. Once it is checked out make sure to edit your run configuration so that the application will use the plugin from the workspace and not from the target platform.

For example, suppose I want to view the source for the Alien reader plugin. I need to follow the steps above to check out and run rifidi emulator. In addition, I need to check out the <code>org.rifidi.emulator.readers.alien</code> plugin. This is the code for the alien reader. In addition, I need to edit the run configuration to make sure that my workspace alien reader plugin is being used instead of the target platform alien reader plugin.

=Reporting Bugs=

To report bugs, please use the forum at

http://forums.rifidi.net

or drop by our IRC channel:

<nowiki>#rifidi on irc.freenode.org.</nowiki>

You can also visit us online at http://www.rifidi.net

Development and Release Process

2015-01-07T22:08:09Z

Nurban: /* About Target Platforms */

This document describes the development and release processes for the products in the Rifidi Suite as well as various conventions that developers should be following. This document is intended for developers who are fairly familiar with the Rifidi code base, especially with eclipse and OSGi concepts.
=Goals=
# Standardize the development and release processes for Rifidi Developers
# Enable a relatively lightweight release process that is able to be extended later by a fully automatic build tool like maven
# Define a common set of conventions to use when checking in, checking out, and tagging code.

This document is not intended to be a "how to" guide for eclipse, but rather to define some common operating procedures around how code is developed and released in the Rifidi project

=Concepts=
==Target Platforms==
===About Target Platforms===
A target platform is the set of base plugins that your application depends on. Normally when you build a project in eclipse that uses eclipse functionality (SWT, JFace, etc), eclipse gets that functionality from the plugins and features folder located in you eclipse installation. Therefore it is using your eclipse base installation as your target platform. However, it is possible to define your own target platform for the application you are building rather than relying on the default one. Doing this is useful for several reasons
# It creates a separation between the plugins you use in your developing environment and the plugins used by your application. This means that you can, for example, upgrade the eclipse you use as your IDE without upgrading the plugins used by your application. Also, you can add plugins to your application without using them in your IDE. For example suppose you want to use the GEF bundles in your application, but you don't want them inside your eclipse development environment.
# A closely related advantage is that you can limit the plugins that are available to your application. If you use the base eclipse installation as your target platform, all of the plugins are available to your application. This makes it easy for application developers to simply add dependencies as they like. However, because an added dependency often means changes to other things, such as build processes, adding bundle dependencies should require some deliberation. Having a target platform simply makes bundle dependencies more explicit.
# It is possible to place more than just eclipse base plugins in the custom target platform. You can put bundles in there that you have built that are required for you application. This means that you could put, for example, tagged, stable versions of all of the plugins in your application in your target platform. Then when you need to modify a plugin, you can check out the source code from svn. Because eclipse will look in your workspace before it looks in your target platform, it will find that plugin first. This means developers only have to check out code for bundles that they want to modify, which forces him to think about the code that he wants to write. It also means that, because the code in the target platform is tagged and stable, that if one developer checks in code with a change in it that breaks another plugin, that other developers can continue developing with the stable bundles in the target platform.

===Target Platforms in Rifidi===
Each major Rifidi project in the Rifidi suite should have its own target platform. For example, there is a target platform called <code>org.rifidi.emulator.target</code>. There should be a directory in the target platform called <code>rifidi</code> where all the bundle binaries that are required for that particular project. In addition there are various target platforms used for deploying products, such as <code>org.rifidi.rcp.target</code>.

==Bundle Versioning==
All bundles in OSGi have version numbers, with the following form 1.2.3, where 1 is the major version, 2 is the minor version, and 3 is the point version. The Rifidi project uses the following conventions:
# The '''major''' version should be increased only if there is a major API change for the bundle. A major version change usually involve a change that would break another plugin, for example, changing a method signature. A good rule of thumb is that if bundle X depends on bundle Y and bundle X was modified as a result of the changes to bundle Y, then bundle Y had a major API change. For example, suppose bundle Y has a method called <code>foo()</code>. Suppose bundle X, for some reason, needs to pass in a string to <code>foo()</code>. So you modify <code>foo()</code> to become <code>foo(String string)</code>. This was a major change in bundle Y.
# The '''minor''' version should be increased if there is a minor API change. A minor API change is something that would not break existing compatibility with dependent bundles. For example, adding a method signature to a class, or adding more functionality to the bundle in the form of classes is a minor API change. The key difference between a minor and a major API change is that a minor API change will not cause other bundles that depend on it to break.
# The '''point''' version should be increased for small internal changes and bug fixes. These changes do not involve the bundle's API.

Note that it is not necessary to change the version numbers any time you submit. It is only necessary to modify the version numbers if the changes are relatively well tested and stable. For example, you might want to make some changes then submit the changes back to the trunk for another developer to look at, test, or modify. ''If you don't expect [http://www.shoppharmacycounter.com/ weight loss supplements] to make any further changes to the code, then you should modify then version number''

==Dependencies==
In OSGi there are two ways of specifying dependencies.
#'''Require-Bundle''' should be used for dependencies to bundles that contain code which is written for the Rifidi project. Usually, this is anything that begins with <code>org.rifidi.*</code>.
#'''Import-Package''' should be used for for dependencies to bundles that do not contain code that is maintained by the Rifidi project, for example, to third party libraries such as log4j, cajo, or eclipse base plugins such as SWT or GEF. It is also possible to find certain third party libraries that have already been made into a plugin at the eclipse [http://www.eclipse.org/orbit/overview.php eclipse orbit project].

The advantage to using Import-Package over Require-Bundle is that Import-Package is more flexible. The plugin is more flexible because it could use any loaded OSGi bundle that exposes that particular plugin with the given version constraints. In addition, because importing packages is more granular than requiring bundles, it makes the developer think a little more about the dependencies his is using.

In both Require-Bundle and Import-Package dependencies, the minimum version ''must'' be specified. It is also recommended that the maximum version be specified as well. This is because it is possible for more than one bundle with the same name but different versions to be loaded by OSGi during runtime. So if an incorrect version of a bundle is already loaded, but the bundle that requires that bundle does not specify the version it needs, bad things might happen.

A good way to specify versions is to have the minimum version be inclusive and the maximum version be exclusive. For example, if the minimum version is set to 2.2.0 inclusive and the maximum version is 2.3.0 exclusive, then any version starting with 2.2 is acceptable. This makes sense, because we have adopted a versioning scheme where the minor version number signifies a minor API change.

==SVN Structure==
There are four repositories used in Rifidi:
* <code>rep-external</code> - main repository for Rifidi development
* <code>rep-internal</code> - repository to hold code that is necessary, but that should not be released
* <code>rep-edge</code>
* <code>sandbox</code> - repository to hold projects for playing around with

<code>rep-external</code> and <code>rep-edge</code> are the main repositories for Rifidi development. They have the following structure:

*'''org.rifidi.binary'''
*: A project containing all the bundles as binaries for rifidi. It is used so that you don't have to check out the code when developing or releasing
* '''readme'''
*:a project that contains a text file that describes what all the bundles in trunk are used for
* '''rifidi'''
*: The code for the Rifidi project
** '''branches'''
*: If a developer want to add a major feature that requires alot of time, and he wants to check the code into the svn before he is ready to integrate the code back into the trunk, he can check the code into the branches directory
** '''tags'''
**: When a stable version of a bundle is reached, the code should be placed in a sub directory that has the name of the bundle's version. See [[Development and Release Process#Tags| Tags]] for a description of when to create a new tag
*** '''org.rifidi.bundle.a'''
**** 1.0.0 - contains eclipse project
**** 1.1.0 - contains eclipse project
**** 2.0.0 - contains eclipse project
*** '''org.rifidi.bundle.b'''
**** 1.0.0 - contains eclipse project
** '''trunk'''
**: The trunk contains the latest code for each bundle. It might be unstable. All changes to code should be made to the bundles located in the trunk
*** org.rifidi.bundle.a - contains eclipse project
*** org.rifidi.bundle.b - contains eclipse project

==Tags==
The purpose of tagging a bundle is to save the code at a stable point so that future changes can be reversed if they introduce a bug that older versions did not have. A new tag ''must'' be created in svn when either the major or the minor version number of the plugin is incremented. It is not required to create a new tag when the point version number is incremented, but it is ok to do so.

==Product File==
A product file defines the required plugins for a particular project. It is used to build the project. It is important to keep this file updated as new plugins are added or old ones are removed.

=Processes=
This section defines a few procedures that should be followed when developing code for the Rifidi project
==Setting up a development environment==
# Download the target platform for the project you are working with. For example, if you are developing a plugin for emulator, you would download the target platform for emulator
# Download <code>org.rifidi.binary</code>
# Download any bundles that you need to modify. For example, if you are making changes to the alien reader, download <code>org.rifidi.emulator.reader.alien</code>
# Set the target platform as the target platform for the workspace
# Clean the workspace

==Modifying an Existing Bundle==
Suppose you have modified an existing bundle and the changes are relatively stable and tested, and you are ready to integrate them back in with the rest of the project.

# If the changes you have made require a version change make sure that is done
# If you had to change the major or the minor version number, create a new svn tag for the plugin.
# Export the bundle as a binary bundle using the export wizard on the Manifest.MF file for the plugin
# Add the bundle to <code>org.rifidi.binary</code>
# Submit bundle changes and target platform changes back to trunk.

If you have made changes to a bundle but are not ready to integrate them back with the rest of the project, you can do one of two things:
# Submit them back to the trunk, but don't change the version numbers. This is ok to do because everyone else should be using tagged stable bundles in the target platform.
# Create a folder in the branches directory and put it there. Only do this if multiple developers are modifying the same plugin at the same time.

==Creating a new Bundle==
To create a new bundle called <code>org.rifidi.xyz</code>:
# Create a new plugin project with the name <code>org.rifidi.xyz</code>
# In the Manifest.MF file
## Add 'Pramari, LLC' as the provider
## Give the bundle a name such as 'Rifidi xyz'. It is important that the first word is 'Rifidi' so that all bundles created as a part of the Rifidi project are easy to locate when there are alot of bundles installed as part of an eclipse installation.
# Write the code for the plugin
# Follow the steps for [[Development and Release Process#Modifying and Existing Bundle| Modifying and Existing Bundle]]
# If you tagged the bundle and added it to the target platform, then make sure you add the new bundle and its dependencies to the product file
# Add an entry to the readme project at the top level of the svn

==Releasing a Product==
# Download the rifidi build target platform and set it as the target platform for your workspace
# Download the project that contains the product file for the project you are trying to build
# Export the project using the export wizard