FreshroastSR700 Package

freshroastsr700 module

class freshroastsr700.freshroastsr700(update_data_func=None, state_transition_func=None, thermostat=False, kp=0.06, ki=0.0075, kd=0.01, heater_segments=8, ext_sw_heater_drive=False)

Bases: object

A class to interface with a freshroastsr700 coffee roaster.

Args:

update_data_func (func): A function to call when this object receives new data from the hardware. Defaults to None.

state_transition_func (func): A function to call when time_remaining counts down to 0 and the device is either in roasting or cooling state. Defaults to None.

thermostat (bool): thermostat mode. if set to True, turns on thermostat mode. In thermostat mode, freshroastsr700 takes control of heat_setting and does software PID control to hit the demanded target_temp. Defaults to False.

ext_sw_heater_drive (bool): enable direct control over the internal heat_controller object. Defaults to False. When set to True, the thermostat field is IGNORED, and assumed to be False. Direct control over the software heater_level means that the freshroastsr700’s PID controller cannot control the heater. Since thermostat and ext_sw_heater_drive cannot be allowed to both be True, this arg is given precedence over the thermostat arg. Note that

(thermostat=False, ext_sw_heater_drive=False), (thermostat=True, ext_sw_heater_drive=False), (thermostat=False, ext_sw_heater_drive=True),

are all acceptable arg combinations. Only the

(thermostat=True, ext_sw_heater_drive=True),

cominbation is not allowed, and this software will set thermostat=False in that case.

kp (float): Kp value to use for PID control. Defaults to 0.06.

ki (float): Ki value to use for PID control. Defaults to 0.0075.

kd (float): Kd value to use for PID control. Defaults to 0.01.

heater_segments (int): the pseudo-control range for the internal heat_controller object. Defaults to 8.

auto_connect()

Starts a thread that will automatically connect to the roaster when it is plugged in.

connect()

Attempt to connect to hardware immediately. Will not retry. Check freshroastsr700.connected or freshroastsr700.connect_state to verify result. Raises:

freshroastsr700.exeptions.RoasterLookupError

No hardware connected to the computer.

connect_state

A getter method for _connect_state. Indicates the current connection state this software is in for FreshRoast SR700 hardware. Returns:

freshroastsr700.CS_NOT_CONNECTED

the software is not currenting communicating with hardware, neither was it instructed to do so. A previously failed connection attempt will also result in this state.

freshroastsr700.CS_ATTEMPTING_CONNECT

A call to auto_connect() or connect() was made, and the software is currently attempting to connect to hardware.

freshroastsr700.CS_CONNECTED

The hardware was found, and the software is communicating with the hardware.

connected

A getter method for _connected. Indicates that the this software is currently communicating with FreshRoast SR700 hardware.

cool()

Sets the current state of the roaster to cool. The roaster expects that cool will be run after roast, and will not work as expected if ran before.

current_temp

Current temperature of the roast chamber as reported by hardware.

Returns:

(int) current temperature, in degrees Fahrenheit

disconnect()

Stops the communication loop to the roaster. Note that this will not actually stop the roaster itself.

fan_speed

Get/Set fan speed. Can be 1 to 9 inclusive.

Args:

Setter: fan_speed (int): fan speed

Returns:

Getter: (int): fan speed

get_roaster_state()

Returns a string based upon the current state of the roaster. Will raise an exception if the state is unknown.

Returns:

‘idle’ if idle, ‘sleeping’ if sleeping, ‘cooling’ if cooling, ‘roasting’ if roasting, ‘connecting’ if in hardware connection phase, ‘unknown’ otherwise

heat_setting

Get/Set heat setting, 0 to 3 inclusive. 0=off, 3=high. Do not set when running freshroastsr700 in thermostat mode.

Args:

Setter: heat_setting (int): heat setting

Returns:

Getter: (int): heat setting

heater_level

A getter method for _heater_level. When thermostat=True, value is driven by built-in PID controller. When ext_sw_heater_drive=True, value is driven by calls to heater_level(). Min will always be zero, max will be heater_segments (optional instantiation parameter, defaults to 8).

idle()

Sets the current state of the roaster to idle.

roast()

Sets the current state of the roaster to roast and begins roasting.

set_state_transition_func(func)

THIS FUNCTION MUST BE CALLED BEFORE CALLING freshroastsr700.auto_connect().

Set, or re-set, the state transition function callback. The supplied function will be called from a separate thread within freshroastsr700, triggered by a separate, internal child process. This function will fail if the freshroastsr700 device is already connected to hardware, because by that time, the timer process and thread have already been spawned.

Args:

state_transition_func (func): the function to call for every state transition. A state transition occurs whenever the freshroastsr700’s time_remaining value counts down to 0.

Returns:

nothing

sleep()

Sets the current state of the roaster to sleep. Different than idle in that this will set double dashes on the roaster display rather than digits.

state_transition_run(event_to_wait_on)

This is the thread that listens to an event from the timer process to execute the state_transition_func callback in the context of the main process.

target_temp

Get/Set the target temperature for this package’s built-in software PID controler. Only used when freshroastsr700 is instantiated with thermostat=True.

Args:

Setter: value (int): a target temperature in degF between 150 and 551.

Returns:

Getter: (int) target temperature in degF between 150 and 551

terminate()

Stops the communication loop to the roaster and closes down all communication processes. Note that this will not actually stop the roaster itself. You will need to instantiate a new freshroastsr700 object after calling this function, in order to re-start communications with the hardware.

time_remaining

The amount of time, in seconds, remaining until a call to the state_transition_func is made. can be set to an arbitrary value up to 600 seconds at any time. When a new value is set, freshroastsr700 will count down from this new value down to 0.

time_remaining is decremented to 0 only when in a roasting or cooling state. In other states, the value is not touched.

Args:

Setter: time_remaining (int): tiem remaining in seconds

Returns:

Getter: time_remaining(int): time remaining, in seconds

total_time

The total time this instance has been in roasting or cooling state sicne the latest roast began.

Returns:

total_time (int): time, in seconds

update_data_run(event_to_wait_on)

This is the thread that listens to an event from the comm process to execute the update_data_func callback in the context of the main process.

class freshroastsr700.heat_controller(number_of_segments=8)

Bases: object

A class to do gross-level pulse modulation on a bang-bang interface.

Args:

number_of_segments (int): the resolution of the heat_controller. Defaults to 8. for number_of_segments=N, creates a heat_controller that varies the heat between 0..N inclusive, in integer increments, where 0 is no heat, and N is full heat. The bigger the number, the less often the heat value can be changed, because this object is designed to be called at a regular time interval to output N binary values before rolling over or picking up the latest commanded heat value.

about_to_rollover()

This method indicates that the next call to generate_bangbang_output is a wraparound read. Use this to determine if it’s time to pick up the latest commanded heat_level value and run a PID controller iteration.

generate_bangbang_output()

Generates the latest on or off pulse in the string of on (True) or off (False) pulses according to the desired heat_level setting. Successive calls to this function will return the next value in the on/off array series. Call this at control loop rate to obtain the necessary on/off pulse train. This system will not work if the caller expects to be able to specify a new heat_level at every control loop iteration. Only the value set at every number_of_segments iterations will be picked up for output! Call about_to_rollover to determine if it’s time to set a new heat_level, if a new level is desired.

heat_level

Set/Get the current desired output level. Must be between 0 and number_of_segments inclusive.

Args:

Setter: value (int): heat_level value, between 0 and number_of_segments inclusive.

Returns:

Getter (int): heat level

freshroastsr700.utils module

freshroastsr700.utils.find_device(vidpid)

Finds a connected device with the given VID:PID. Returns the serial port url.

freshroastsr700.utils.frange(start, stop, step, precision)

A generator that will generate a range of floats.

freshroastsr700.utils.seconds_to_float(time_in_seconds)

Converts seconds to float rounded to one digit. Will cap the float at 9.9 or 594 seconds.

freshroastsr700.pid module

class freshroastsr700.pid.PID(P, I, D, Derivator=0, Integrator=0, Output_max=8, Output_min=0)

Bases: object

Discrete PID control.

getDerivator()

getError()

getIntegrator()

getPoint()

setDerivator(Derivator)

setIntegrator(Integrator)

setKd(D)

setKi(I)

setKp(P)

setPoint(targetTemp)

Initilize the setpoint of PID.

update(currentTemp, targetTemp)

Calculate PID output value for given reference input and feedback.

update_d(d)

update_i(i)

update_p(p)

freshroastsr700.exceptions module

exception freshroastsr700.exceptions.RoasterError

Bases: Exception

A base error for freshroastsr700 errors.

exception freshroastsr700.exceptions.RoasterLookupError

Bases: freshroastsr700.exceptions.RoasterError

Raised when a device is not able to be found from the connected devices.

exception freshroastsr700.exceptions.RoasterStateError

Bases: freshroastsr700.exceptions.RoasterError

Raised when the current state of the roaster is not a known roaster state.

exception freshroastsr700.exceptions.RoasterValueError

Bases: freshroastsr700.exceptions.RoasterError

Raised when a class variable assigned is out of the range of acceptable values.