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.