﻿================================================================
 Using COFFEE HAZEL with Artisan
 SORAMAME LAB INC
================================================================

How to add COFFEE HAZEL readings to the roasting software Artisan.

You can keep your current thermocouple setup (Phidget or anything
else) exactly as it is. Hazel is added on top, as extra sensors.


■ What you need

  - A COFFEE HAZEL unit (firmware V2.3.0 or later)
  - Artisan 4.0.2 or later
  - COFFEE_HAZEL.aset (the settings file included here)

  Firmware can be updated from the unit's own screen.
  Artisan 3.0.0 does not work. Please use 4.0.2 or later.


■ What gets added to Artisan

  Humidity, Temperature     intake air
  Water vapour density 1/2  intake and exhaust
  ΔH2O                      absolute humidity difference,
                            exhaust minus intake
  ΔH2O RoR                  its rate of rise, per minute

  The rate of rise is calculated inside the unit.
  You do not need to build any formula in Artisan.


================================================================
 Setup
================================================================

[1] Switch the UI to Expert mode

    Config → Mode → Expert

    Production and Standard modes hide the device and port
    settings entirely. If you cannot find the menus described
    below, check this first.


[2] Close any roast profile

    File → New

    If a roast profile (.alog) is open, Artisan reloads that
    profile right after you load settings, and the device
    configuration stored in it overwrites what you just loaded.

    This is the usual reason for "I loaded the file but nothing
    changed".


[3] Save your current settings first

    Help → Save Settings...

    Keep this file. It lets you return to your current setup.


[4] Load the settings file

    Help → Load Settings...

    Choose the included COFFEE_HAZEL.aset.

    The file contains only the keys it needs to change, so your
    main device (Phidget or whatever you use) is left untouched.

    * If you already use Extra Devices, read the section
      "If you already use Extra Devices" below BEFORE loading.
      Your extra device list will be replaced.


[5] Enter the IP address of the unit

    Config → Ports → WebSocket tab

    Type the IP address of your COFFEE HAZEL into Host.
    The unit shows its own IP address on its display.

    Leave Port at 81 and Path at WebSocket.

    This is the only value you have to type in by hand, because
    it differs from unit to unit.


[6] Check

    Start recording. Six readings should appear on the right.

      aHum / aTmp        intake humidity and temperature
      aH2O / eH2O        intake and exhaust water vapour density
      dH2O / dH2O RoR    ΔH2O and its rate of rise


================================================================
 If you already use Extra Devices
================================================================

Read this if you have already configured Extra Devices, for
example a second thermocouple, or a virtual curve built from a
math expression.


■ What happens

  Loading the settings file REPLACES the whole Extra Devices
  list with the three COFFEE HAZEL entries. It does not append
  to it. Your existing entries are lost.

  Only these two places are replaced:

    - The Extra Devices list  (Config → Device)
    - The WebSocket settings  (Config → Ports)

  Your main device is not affected. Nothing you do here touches
  it.


■ Before loading, record what you have

  Open Config → Device → Extra Devices and take a screenshot.
  Scroll the table to the right as well, so that columns such as
  Δ Axis are captured too.

  The file you saved in step [3] can also restore it, but that
  rolls back the Hazel settings along with everything else.


■ Two ways forward

  Option A: load the file, then add your devices back

    After loading, rows 1 to 3 are Hazel. Add your own devices
    from row 4 onward:

    Config → Device → Extra Devices → Add

    Hazel occupies the first six inputs, so your channel numbers
    shift. If any math expression refers to a channel by number,
    update those references too.

  Option B: do not load the file, configure by hand

    Choose this if you would rather not touch your current
    setup at all. Entering the values below gives you the same
    result as the settings file.


■ Values for Option B

  ▼ Config → Ports → WebSocket tab

    Host    the IP address of the unit
    Port    81
    Path    WebSocket

    In the table on the same screen, fill in six nodes.
    Leave every Request field empty.

      1  humidity1
      2  temperature1
      3  water_vapor_density1
      4  water_vapor_density2
      5  delta_h2o
      6  delta_h2o_ror

  ▼ Config → Device → Extra Devices tab

    Add three rows and set them as follows.

      Device            Name 1    Name 2      Δ Axis
      -------------------------------------------------
      WebSocket         aHum      aTmp        no
      +WebSocket 34     aH2O      eH2O        both ticked
      +WebSocket 56     dH2O      dH2O RoR    both ticked

    Δ Axis is further right in the table; scroll to reach it.
    Ticking it draws the curve against the right-hand axis,
    where it is readable instead of being flattened against
    the bottom of the temperature scale.

  ▼ Config → Curves → Filters tab

    Untick Limits. The reason is under "If something is wrong"
    below.

  * Row 1, plain "WebSocket" with no number, is normally the
    main device, but it can be selected as an extra device too.
    That row fetches all six values in a single request, which
    keeps traffic down to one round trip every 2 seconds.
    Do not leave it out.


================================================================
 If something is wrong
================================================================

- The readings show "u.u"

    That is Artisan's way of saying "no data". It is not 0.0.

    Config → Curves → Filters, untick Limits.

    That filter discards values outside a range as faulty. It is
    designed for thermocouple temperatures, so it throws away
    small values such as ΔH2O, and negative values of the rate
    of rise.


- Loading the settings file changes nothing

    A roast profile is probably still open. Go back to step [2],
    File → New, and try again.


- The curves are not visible on the graph

    ΔH2O and its rate of rise are small numbers. On the
    temperature scale (0 to 300) they sit flat along the bottom.

    Scroll the Extra Devices table to the right to find Δ Axis.
    With it ticked, the curve is drawn against the right-hand
    axis and becomes readable. The settings file already does
    this for you.


- The readings barely move before roasting

    That is normal. While idle, ΔH2O sits around 0.5 and the
    rate of rise near 0. Once roasting starts ΔH2O climbs to
    somewhere between 9 and 16, and at first crack the rate of
    rise jumps sharply.


================================================================
 Contact
================================================================

  SORAMAME LAB INC
  https://soramamelab.com/contact/

  Note: our online shop and checkout are in Japanese, and we
  currently ship within Japan only.
