Typica User Guide

Once all of the necessary software is installed, you will probably want to do some initial data entry. When you start Typica for the first time or any time the most recently used database is unavailable, you will be prompted to connect to a database.

Enter the information required to connect to the database. This is the same information used to connect to the database with psql. Once all of the fields have been filled out, click the Connect button to connect to the database.

After this, you will be prompted to select a configuration document. Typica comes with three example configurations in the Configurations directory. These are named oneprobe.xml, twoprobe.xml, and manometer.xml. These configurations are all the same except for the window showing the current roasting information. The twoprobe.xml configuration is used at the production roaster at Wilson's Coffee & Tea, a Diedrich IR-12 which has been modified to have a second thermocouple for measuring the temperature of the air around the bean. As such, this configuration displays two sets of current temperature data and provides controls for starting and stopping the logging, buttons to quickly annotate the log with airflow changes, and a button to annotate the log with a sample identification which can be used when cupping multiple samples pulled at different points along a single roast. The oneprobe.xml configuration is identical, but only provides a single series of current temperature data. This is used at the sample roaster, a Diedrich SR-1. The manometer.xml configuration is used at another firm. This provides two sets of temperature measurements and lacks the controls used for annotating air flow changes. Instead, a numeric input control is provided for annotating the log with manometer readings. Choose the configuration that most closely resembles your setup. You may also want to examine the configuration files and modify them to more closely match your setup. If you run into problems with this, please contact the author for assistance.

The next window provides access to several features of Typica. The first time Typica is run, you should click the Setup Database button. This will create the database tables Typica uses to store your data. After this, you can start to enter some information about your coffee roasting equipment and your coffees.

Click the New Roaster button. You will see two fields, one for the roaster name and another for the roaster number. The roaster number should be unique among the roasters you enter (you may want to start at 1 and increment that number for each roaster you enter). The name should be text that the person operating the roaster will recognize. This information is used to identify which coffee roaster was used to roast a given batch of coffee. Once that information has been entered, click the Submit button. Repeat this step for every coffee roaster you intend to use with Typica.

Next, you can create items specifying a given roasted coffee. Click the Manage Roasted Coffee Items button. The window that comes up can be used for three different tasks. You will be creating new roasted coffee items. To do this, enter the name of the roasted coffee in the text entry field and click the Add New Coffee button. Repeat this for every roasted coffee item. I would recommend also adding a Sample item for use with batches that will not be sold. Later, if a coffee is discontinued and you would like to remove it from the list of roasted coffee items that you select from when entering information on a batch, you can select the item from the Current Items list and click the Remove Item button. If you want to add such an item back into the list of current items, select the coffee from the Discontinued Items list and click the Restore Item button. When you are finished setting up your list of roasted coffee items, close the window.

One more set of information is needed in order to keep track of unroasted coffee inventory. That is, information on the unroasted coffee. Click the Purchase Green Coffee button. This is one of the more complex forms in Typica, but it is used to record several pieces of information that you may find useful later. At the top of this window, you will see a button which can be used to add fields for additional items, a date entry field for entering the purchase date for the coffees entered, a vendor field for entering the supplier of the coffees, and a field for entering the invoice number. For each coffee, you can enter the name of the coffee, its reference number, how much is purchased, the cost (either per pound or total cost), the country and region of origin, the producer, the grade of the coffee, how the coffee was milled and dried, how many bags of coffee were purchased, if the coffee was decaffeinated and if so, by what method, and any number of certifications the coffee might have. Below the fields for entering details of the coffees, it is possible to associate fees with the invoice such as shipping fees or finance charges. The information that is required is the date, vendor, and invoice number, and for each item, the name of the item, the quantity, cost, and origin. If the coffee is decaffeinated, the decaffeination method is also required. All other information is optional. Once all of this information has been entered, click the Submit button.

If you have a current inventory for any of these coffees, click the Update Inventory button. You will be able to select any of the unroasted coffee items with a quantity not equal to 0 and enter the number of pounds or the number of bags available. Select each item in the list, enter the available inventory, and click the Update button. The most convenient way to keep the inventory data consistent with reality is to update the inventory whenever a bag of coffee is emptied. This window also shows the number of pounds and bags in stock for the selected item, so adhering to this procedure makes it easy to check if another bag of coffee needs to be opened or how full a bag of coffee you should be looking for.

If you have roasting data from another Typica user and you would like to make the roast profile from such a file the target roast profile for one of your roasted coffee items, you can click the Import Target Roast Profiles button. Here you will see a list of roasted coffee items and a button which allows you to select the saved data.

You are now ready to record roasting data. Make sure that the DAQ is connected to the thermocouples on your roaster and to the USB port on your computer. The green light on the DAQ should be flashing. You can now click the Roast Coffee button.

The first time you bring up this window, it may not be set up exactly as you would like. The window can be resized, as can the width of columns in the table view. Dragging the space between various elements can be used to adjust the size of each of the temperature and time displays, the table view of the roasting data, and the graph view of the roasting data. Typica will remember how this window was set up and restore all of that the next time you open this window.

If you would like the roast to be recorded in the batch log, select New Batch from the Batch menu. The window that comes up allows you to select which machine you are using to roast the coffee, which roasted coffee you are producing, and which coffee or coffees you are using to produce this roasted coffee. Any number of unroasted coffees can be selected and different weights for each of these can be entered. If you have previously set a saved roast profile as the target roast profile, you can click the Load Profile button to have the previous window show the saved roast profile. Otherwise, click No Profile. At this point, you can still have the logging window show a previously recorded roast. Under the File menu you will see an Open item which can load previously saved roasting data from a file on disk. You can also use the Batch Log to load any previously batch of coffee. Once you have either loaded a target roast profile or opted to roast without one, click the Start Batch button while simultaneously releasing coffee into the roaster. This will begin recording your roasting data. You should see measurements periodically added to the table on the left and you should see a curve being plotted in the graph on the right. You will also see the timer reset to 0:00 and this will begin counting the elapsed batch time.

While you are roasting the coffee, you can change the level of detail in the table view. By default this will show one measurement every 30 seconds along with any measurement with an associated annotation. Items in the Log menu can be used to show different levels of detail. More time between recorded measurements means that less detail is is shown in the table but data from a larger portion of the roast can be seen at a given time. Less time between displayed measurements means that more nuanced changes are visible in the table, but less of the batch is visible at once. If you have been keeping paper records of roasting data, Typica might seem more familiar if the table shows measurements in the same way as the old paper logs. It is also possible to have the table show every measurement collected, however the usefulness of this is limited as only a few seconds of roasting data will be visible at once in such a view.

Once the batch is finished, click the Stop Batch button while releasing coffee from the roaster. This will bring up the window that you had previously entered the batch information in. Once the coffee is cool, you can enter the weight of the roasted coffee and any notes about the batch that you may want to refer to later. The Time and Duration fields will have already been filled in with the time the batch was started and the duration of the batch. There are also two check boxes. The Approved check box should be clicked if you believe the batch was roasted within tolerance. The Save log as target profile check box should be clicked if you want to save the roast profile you have just recorded as the target roast profile for that roasted coffee. If you do this, you will be able to click the Load Profile button on future roasts of that coffee to recall data from that batch. Once this information has been entered, click the Submit button.

You do not need to wait until this information has been entered before starting a new batch of coffee. Under the Batch menu, select New Batch to create another window where information on the next batch can be entered. Any number of windows can be created, but the batch details will not be saved in the database until you click the Submit button.

Before starting a new batch, if you would like to save the recorded roasting data to a file, there are two options in the logging window that can be used. Under the File menu there is a Save item which will save the data to an XML document which can be opened by other Typica users or manipulated by programs that transform XML data. There is also an Export CSV item which saves the data in a form that can be read by spreadsheet applications or other data manipulation programs. Please be aware that these save all recorded measurements for a batch. Depending on the duration of the batch and the number of thermocouples used, this is usually between 1000 and 5000 rows of data. Some programs do not perform well with data sets this large.

The last menu item in the logging window to describe is the Clear Log item in the Log menu. This will remove all measurements from the log. Note that loading a new target profile will also remove the previous content of the log, so this item should not be needed frequently.

Typica can also be used to record cupping data. In order to do this, in the first window, click the New Cupping Session button. Next, specify the samples you intend to cup. Each sample is associated with a measurement from a particular batch of coffee. This means that if you pull a dozen samples from one roast of a coffee and intend to cup all of them, you can select the batch these samples were pulled from, select the sample points, and add all of them to the cupping session. Any number of samples from any number of batches can be added to a given cupping session. It is also possible to name the cupping session and associate it with an event. Each sample should be given a unique (within the session) sample ID and the order of samples on the table can also be specified. Once the cupping session has been fully specified, save the session to the database. At this point, you can click Join Cupping Session. This will display a list of open cupping sessions. Once a session is selected, a window will come up providing a cupping form for each sample in the session. The cupping form provided is based on the SCAA and Q cupping forms with some additional note areas based on the author's observations of how skilled cuppers make use of the paper forms. In order to save screen space, the scored attributes are split into four sections, only one of which is shown at a time for each sample. The first page allows observations on the aroma to be recorded. The second page is used for entering flavor, acidity, and body. The third page shows balance, aftertaste, and overall. The fourth provides uniformity, clean cup, and sweetness. Items in the Sections menu allows for switching among these pages. Notes, taints, and faults fields are always available and the total and final scores for each sample are also automatically calculated and are likewise always displayed. The sample ID is also always shown. If the database is available to other computers on the network with Typica installed, any number of people can join a given cupping session. The form provided is also well suited to transcribing data from paper cupping forms. Typica is currently rather limited in the analysis of cupping data, but most common analyses can be carried out either with SQL queries on the database or by exporting the records of interest to a spreadsheet and using the statistical methods made available by the spreadsheet application. Expect future configuration updates to make Typica more useful for working with cupping data.

Finally, the first window has a Reports menu. The items in this menu display information such as recent coffee production and current coffee inventory. The reports provide summary information which can be examined or printed. There are not many reports provided by the example configurations. Future configuration updates will provide additional reports.