neal
/
Typica


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306
							<html>
	<head>
		<title>Typica - Data for Coffee Roasters</title>
		<link rel="stylesheet" type="text/css" href="../style.css">
	</head>
	<body>
		<div id="page">
			<div id="topmatter">
				<div id="topbanner">
					<img src="../logo96.png" height="96px" width="96px" alt="Typica logo" />
					<h1>Typica</h1>
					<h2>Data for Coffee Roasters</h2>
				</div>
				<div id="menu">
					<a class="tab" href="../index.html">Project Home</a>
					<a class="tab" href="../downloads.html" >Downloads</a>
					<a class="tab active" href="../documentation.html" >Documentation</a>
					<a class="tab" href="../screenshots.html" >Screenshots and Videos</a>
					<a class="tab" href="../involvement.html" >Get Involved</a>
					<a href="http://appliedcoffeetechnology.tumblr.com/tagged/Typica" class="tab">Blog</a>
				</div>
			</div>
			<div id="maintext">
				<ul>
					<li><a href="#database">Database Connection</a></li>
					<li><a href="#configfile">Open Configuration File</a></li>
					<li><a href="#hardware">Configuring Typica for your Hardware</a></li>
				</ul>
			
				<h1>Running Typica for the First Time</h1>
				
				<p>After downloading Typica and extracting the contents of the .zip (Microsoft Windows) or
				copying the contents of the .dmg (Mac OS X) to a more convenient location, you should have
				a folder that contains three other folders. The <tt>source</tt> folder contains all of
				the source code for Typica which you may use if you want to modify the software. This
				folder also contains a file called <tt>typica.pdf</tt> which has complete documentation
				of how Typica works (not how to use Typica). You do not need to read that to use Typica,
				but you may still find it interesting. The contents of this folder are not required to
				run Typica and may be deleted if you have no use for it. The <tt>configuration</tt> folder
				contains an example configuration for Typica to use. These files can be modified to perform
				extensive customization of Typica or to add or remove reports if you want to change how
				Typica works, however most do not have a need to modify any of these files. Typica requires
				that the contents of this directory exist for proper operation. The <tt>program</tt> folder
				contains the Typica executable and its library dependencies. On Mac OS X this is instead
				all collected in an .app bundle.</p>
				
				<p>Find either Typica.exe (Microsoft Windows) or Typica.app (Mac OS X) and double click
				to open the program.</p>
				
				<img src="images/explorer.png" />
				
				<a name="database" />
				<h2>Database Connection</h2>
				
				<img src="images/dbconnect.png" />
				
				<p>The first time you start Typica, you will be asked for the information needed to
				connect to a database. If you have not installed PostgreSQL, you can click Cancel to
				continue without connecting to a database. Note that doing so will result in Typica
				having a very limited feature set. If you have installed PostgreSQL on the same
				computer as Typica, the host name should be set to <tt>localhost</tt>. If PostgreSQL
				is running on a different computer you will need to specify the IP address of that
				computer.</p>
				
				<p>If you have set up a database for Typica to use, the name of that database
				should be set as the database name, otherwise the PostgreSQL installer creates a
				database named <tt>postgres</tt> which you can use.</p>
				
				<p>Similarly, if you have created a new database
				user role for Typica, the user name and password that you chose for this should be
				entered as the user name and password here. Otherwise, the PostgreSQL installer creates
				a user named <tt>postgres</tt> with the password that you chose during the installation
				process.</p>
				
				<p>Once all of this has been entered, click Connect.</p>
				
				<p>You only need to enter this information the first time you start Typica. It will
				not prompt for this information in the future unless Typica fails to connect to the
				database or unless you select a menu item that instructs Typica to forget the
				connection settings.</p>
				
				<h3>Troubleshooting: What if it Doesn't Work?</h3>
				
				<p>The problem is <em>not</em> with Typica. If you are running PostgreSQL on the same
				computer as you are running Typica, you have most likely typed something incorrectly.
				You can use the SQL Shell (psql) to verify that your login information is correct. If
				you can connect on port 5432, the same information used to connect with psql will also
				be usable with Typica. Another possibility is that PostgreSQL is not currently running.
				If you are running PostgreSQL on a different computer, make sure that the other computer
				is turned on, that PostgreSQL is running, and that it is configured to accept connections
				from the network.</p>
				
				<a name="configfile" />
				<h2>Open Configuration File</h2>
				
				<p>Every time you open Typica, you will be asked to open a configuration file. Typica
				comes with one example configuration file that meets most needs, however you can
				create your own if you have special requirements. This documentation assumes that you
				are using the provided example configuration.</p>
				
				<p>The first time you start Typica or when using a new version of Typica for the first
				time, you may find that this prompt shows files in the wrong directory. Typica will show
				files from the most recently used directory or if there isn't one, a platform dependent
				default.</p>
				
				<img src="images/config1.png" />
				
				<p>This is a normal Open File window which works the same as when you select the Open
				menu item in most programs. A number of controls are available to change to the correct
				directory. You want to be in the <tt>configuration</tt> folder described previously.</p>
				
				<img src="images/config2.png" />
				
				<p>Once you are in the correct directory, select <tt>config.xml</tt> and click Open.</p>
				
				<img src="images/config3.png" />
				
				</p>The next window you see should look like this:</p>
				
				<img src="images/nav.png" />
				
				<h3>Troubleshooting: It Opened Internet Explorer and is showing me gobbledygook.</h3>
				
				<p>If this happens, you were not selecting the configuration file from within Typica.
				Go back to Typica and try again. In particular, note the title bar of the window you
				are in. See the screenshots above where it says "Open Configuration File". If your
				window doesn't say that, you're not in Typica. You may think you are, but you're wrong.</p>
				
				<h3>Troubleshooting: I opened a file and nothing is happening.</h3>
				
				<p>Exit Typica and try again. You most likely selected the wrong file to open. Please
				go back to the description of which file is required, read the instructions, and follow
				them carefully.</p>
				
				<h3>Tip: Bypass the Configuration Prompt</h3>
				
				<p>Typica has a command line option available for specifying which configuration file
				should be used. To do this, use -c and the path to the configuration you want to open.
				This will prevent the configuration prompt from appearing. On Microsoft Windows, you
				can do this by creating a shortcut. In Windows Explorer, go to the directory containing
				Typica.exe. Right click and select "Create shortcut".</p>
				
				<img src="images/shortcut.png" />
				
				<p>Now right click the shortcut and select Properties.</p>
				
				<img src="images/properties.png" />
				
				<p>Find the field labeled Target. At the end of the line after the quotation mark, add
				a space and <tt>-c ../configuration/config.xml</tt> and click OK. The portion of the
				line that reads <tt>../configuration/config.xml</tt> is the path to your desired
				configuration file relative to the directory with the program. You can also use an
				absolute path to the file starting with <tt>C:\</tt> on Microsoft Windows or <tt>/</tt>
				on other platforms.</p>
				
				<h3>Tip: Pin the Shortcut for Convenient Access</h3>
				
				<p>The shortcut created in the previous tip can be moved anywhere for convenient
				access. You can right click that and find options to pin that to the task bar for
				convenient single click access. On Windows 7 you can also pin that to the start menu
				and on Windows 8 you can pin that to the start screen.</p>
				
				<a name="hardware" />
				<h2>Configuring Typica for your Hardware</h2>
				
				<h3>Hardware</h3>
				
				<p>Once you've started Typica and selected your configuration file, you should see
				the main navigation window. It looks like this:</p>
				
				<img src="images/nav.png" />
				
				<p>The first time you use Typica you will not have any coffee roasters configured
				for use. This also applies for people who have used older versions of Typica and are
				now upgrading to version 1.4 or later. To do this, click the Configure Roasters button.
				This will bring up a new window with two panels. In the lower left you will see a
				button labeled +. Click that to add your first coffee roaster.</p>
				
				<p>Now you will see an item in the left panel. You can double click on that to
				rename it if you want. Whatever you name this is what will appear in the list in
				the navigation window. Choose a name that you'll recognize as the particular machine
				you'll be using.</p>
				
				<p>When you click on the roaster in the left panel you will see some details in the
				right panel.</p>
				
				<img src="images/rconfig1.png" />
				
				<p>Next to "Machine ID for database" you should enter a number. This ID number will
				be used to identify this roaster in the database and it will be associated with every
				batch of coffee you roast. If you have used an older version of Typica, you can use
				the same number that you had specified previously to maintain continuity. If you are
				setting up Typica for the first time, just use 1 for your first roaster, 2 for your
				second, and so on.</p>
				
				<p>You will also see three buttons: "Add Device", "Add Annotation Control", and
				"Advanced Features". First we will want to use the Add Device button to specify the
				data acquisition hardware you will use to connect this coffee roaster to your
				computer.</p>
				
				<p>You should see up to three items in a menu when you click "Add Device". Select
				the one matching the hardware that you intend to use. You will find a new item on
				the left matching your selection.</p>
				
				<p>In the case of NI-DAQmx Base or NI-DAQmx, clicking the new item in the left panel
				will change the right panel to display a single button: "Add Device". Click this to
				see a list of supported hardware and click the item that matches the hardware you
				have. In the case of NI-DAQmx, you can select "NI USB 9211A" for any supported USB
				carrier containing a NI 9211 module. Whichever you choose, you will have a new item on
				the left.</p>
				
				<p>If you instead selected "Modbus RTU Device", you will want to connect the hardware
				to your computer before continuing. Once you click the new item in the left panel
				Typica will attempt to detect any serial port on your computer and if your RS-485 to
				USB serial adapter is not connected, it will not be shown. Click the item and you
				will see all of the details for configuring Typica to use your Modbus RTU device.</p>
				
				<img src="images/modbusconfig.png" />
				
				<p>The appropriate settings here depend on settings that must be configured on the
				Modbus RTU device and they depend on which device you have. You will require both
				the operator manual and the communications manual for your device to determine the
				correct settings for your hardware.</p>
				
				<p>If you selected NI DAQmx and then NI USB TC01, you will have an item on the
				left representing that device. Clicking this will show three settings.</p>
				
				<img src="images/tc01config.png" />
				
				<p>The Device ID is how the National Instruments software identifies the device. In
				the case of this hardware, this will be Dev<em>n</em> where <em>n</em> is some number.
				This will most likely be <tt>Dev1</tt> but you can verify this in National Instrument's
				Measurement & Automation Explorer. The Column Name indicates the name of the column
				where measurements from this device will be placed in the table view of your roasting
				data. A short, one word identifier is recommended for this. Note that certain advanced
				features will require knowing a column name. The Thermocouple Type should match the type
				of thermocouple you have in your roaster. If the wrong thermocouple type is specified,
				your measurements will not be correct. Finally, if you double click this item on the
				left, you can rename it. Whatever the item is named on the left is what will be displayed
				on the indicator showing the most recent measurement. This can be a longer descriptive
				name.</p>
				
				<p>In the case of NI 9211 based devices used either through NI DAQmx or NI DAQmx Base,
				clicking the new item on the left will show a Device ID field and an Add Channel button.
				If you are using NI DAQmx Base, this will be Dev<em>n</em> where <em>n</em> is a number
				starting with 1 for the first connected device. If you only have one device, this will
				be <tt>Dev1</tt>. If you are using NI DAQmx, some hardware will follow this convention
				and some will not. You should check for the appropriate device ID in Measurement &
				Automation Explorer. Ensure that you are looking at the item representing the device
				itself and not just the chassis the device is plugged into. Once the Device ID is
				specified, you can click Add Channel to add as many thermocouple channels as you have
				connected to this device. With this hardware it is recommended that you do not connect
				more than three thermocouples to a single device and these should be wired starting
				from TC0.</p>
				
				<p>For each channel, you can double click the item on the left to change the text that
				will appear in the indicator showing the most recent measurement. When you click on
				these you will see on the right settings for Column Name and Thermocouple Type. The
				Column Name will appear at the top of the table view in the column where measurements
				from this channel are placed. A short one word name is recommended. This name should
				be unique across all channels configured for a particular roaster. The thermocouple
				type must match the type of the thermocouple connected on that channel. If it does not,
				your measurements will not be correct.</p>
				
				<h3>Annotation Controls</h3>
				
				<p>If you click the item on the left representing your roaster, one of the available
				buttons is "Add Annotation Control". Clicking this will provide three options:
				"Annotation Button", "Counting Button", and "Numeric Entry". These controls can be
				used to add annotations to your roasting data as you roast. If you don't want to do
				this, you don't need to add any of these controls.</p>
				
				<p>An Annotation Button is used to make note of an event fixed at a particular moment
				in time. If your roaster has a control with a small number of states, you can have a
				different button for each state and when you activate that button it will place a
				note at the most recent measurement. Some use this to note airflow control changes,
				some prefer to note details such as the start of first crack. Clicking the item on the
				left representing your annotation button will show two settings on the right. The
				Button Text is the text that will appear on the button and the Annotation Text is the
				text that will appear in the log when the button is activated. You can have any number
				of these buttons, but it is recommended to keep the number small.</p>
				
				<p>A Counting Button is like an Annotation Button but you can have as part of the
				annotation text a number corresponding to the number of times the button has been
				clicked. This is useful when pulling several samples from a roast for roast profile
				development as you will have a unique identifier for each sample you pull which you
				can reference later when attempting to replicate your desired roast. It is recommended
				that you only have one Counting Button.</p>
				
				<img src="images/countconfig.png" />
				
				<p>Numeric Entry provides a way to provide notes with numeric data that cannot be
				logged automatically. Some roasters have fuel or air flow controls with a large number
				of numerically identified settings. Some people may want to occassionally note the
				reading from a manometer. This is the control to do that. Clicking the item representing
				a Numeric Entry on the left will show several options allowing you to specify how the
				field is identified on the screen, minimum and maximum values, and the number of places
				after the decimal point to allow. All of these must be set to some value. Optionally you
				can also specify prefix text and/or suffix text. The content of these fields will be
				included in the annotation before or after the entered number. This can be used to make
				clear which control adjustment is represented or the unit a measurement reading was
				taken in.</p>
			</div>
		</div>
	</body>
</html>