text: """
  ---------------------
  The MIT License (MIT)
  
  Copyright (c) 2017-2018 Sungeun K. Jeon for Gnea Research LLC
  
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:
  
  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.
  
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE.
  ---------------------
  """
  
  
  """
  This Python script produces a continuous piece-wise line fit of actual spindle speed over
  programmed speed/PWM, which must be measured and provided by the user. A plot of the data
  and line fit will be auto-generated and saved in the working directory as 'line_fit.png'.
  
  REQUIREMENTS:
    - Python 2.7 or 3.x with SciPy, NumPy, and Matplotlib Python Libraries
    
    - For the most people, the easiest way to run this script is on the free cloud service
      https://repl.it/site/languages/python3. No account necessary. Unlimited runs. 
      
      - Last checked on 4/5/2018. This site has been regularly evolving and becoming more 
        powerful. Things may not work exactly as shown. Please report any issues.
      
      - To use, go to the website and start the Python REPL. Copy and paste this script into
        the main.py file in the browser editor. Click 'Run' and a solution should appear in 
        the text output in the REPL console window. You can edit the script directly in the
        browser and re-run the script as many times as you need. A free account is only 
        necessary if you want to save files on their servers.
        
      - This script will also automatically generate a png image with the plot of the data 
        with the piece-wise linear fit over it, but this will not show up by default on this 
        website. To enable this, just click the 'Add File' icon and create a dummy file. 
        Name it anything, like dummy.py. Leave this file blank. Doing this places the REPL 
        in multiple file mode and will enable viewing the plot. Click the 'Run' icon. The
        solution will be presented again in the console, and the data plot will appear in 
        the file list called 'line_fit.png'. Click the file to view the plot.
    
    - For offline Python installs, most Mac and Linux computers have Python pre-installed 
      with the required libraries. If not, a quick google search will show you how to 
      install them. For Windows, Python installations are bit more difficult. Anaconda and 
      Pyzo seem to work well.
  
  USAGE: 
    - First, make sure you are using the stock build of Grbl for the 328p processor. Most
      importantly, the SPINDLE_PWM_MAX_VALUE and SPINDLE_PWM_MIN_VALUE should be unaltered
      from defaults, otherwise change them back to 255.0 and 1.0 respectively for this test.
      
    - Next, program the max and min rpm Grbl settings to '$30=255' and '$31=1'. This sets
      the internal PWM values equal to 'S' spindle speed for the standard Grbl build.
           
    - Check if your spindle does not turn on at very low voltages by setting 'S' spindle
      speed to 'S1'. If it does not turn on or turns at a non-useful rpm, increase 'S' by 
      one until it does. Write down this 'S' value for later. You'll start the rpm data
      collection from this point onward and will need to update the SPINDLE_PWM_MIN_VALUE 
      in cpu_map.h afterwards.
           
    - Collect actual spindle speed with a tachometer or similar means over a range of 'S' 
      and PWM values. Start by setting the spindle 'S' speed to the minimum useful 'S' from 
      the last step and measure and record actual spindle rpm. Next, increase 'S' spindle 
      speed over equally sized intervals and repeat the measurement. Increments of 20 rpm 
      should be more than enough, but decrease increment size, if highly nonlinear. Complete
      the data collection the 'S' spindle speed equal to '$30' max rpm, or at the max useful 
      rpm, and record the actual rpm output. Make sure to collect rpm data all the way 
      throughout useful output rpm. The actual operating range within this model may be set 
      later within Grbl with the '$30' and '$31' settings.
      
    - In some cases, spindle PWM output can have discontinuities or not have a useful rpm
      in certain ranges. For example, a known controller board has the spindle rpm drop
      completely at voltages above ~4.5V. If you have discontinuities like this at the low
      or high range of rpm, simply trim them from the data set. Don't include them. For 
      Grbl to compensate, you'll need to alter the SPINDLE_PWM_MIN_VALUE and/or 
      SPINDLE_PWM_MAX_VALUE in cpu_map.h to where your data set ends. This script will 
      indicate if you need to do that in the solution output.
             
    - Keep in mind that spindles without control electronics can slow down drastically when 
      cutting and under load. How much it slows down is dependent on a lot of factors, such 
      as feed rate, chip load, cutter diameter, flutes, cutter type, lubricant/coolant, 
      material being cut, etc. Even spindles with controllers can still slow down if the 
      load is higher than the max current the controller can provide. It's recommended to 
      frequently re-check and measure actual spindle speed during a job. You can always use 
      spindle speed overrides to tweak it temporarily to the desired speed.
  
    - Edit this script and enter the measured rpm values and their corresponding 'S' spindle 
      speed values in the data arrays below. Set the number of piecewise lines you would 
      like to use, from one to four lines. For most cases, four lines is perfectly fine.
      In certain scenarios (laser engraving), this may significantly degrade performance and
      should be reduced if possible. 
    
    - Run the Python script. Visually assess the line fit from the plot. It will not likely 
      to what you want on the first go. Dial things in by altering the line fit junction 
      points 'PWM_pointX' in this script to move where the piecewise line junctions are 
      located along the plot x-axis. It may be desired to tweak the junction points so the 
      model solution is more accurate in the region that the spindle typically running. 
      Re-run the script and tweak the junction points until you are satified with the model.
      
    - Record the solution and enter the RPM_POINT and RPM_LINE values into config.h. Set the 
      number of piecewise lines used in this model in config.h. Also set the '$30' and '$31'
      max and min rpm values to the solution values or in a range between them in Grbl '$' 
      settings. And finally, alter the SPINDLE_PWM_MIN_VALUE in cpu_map.h, if your spindle 
      needs to be above a certain voltage to produce a useful low rpm.
      
    - Once the solution is entered. Recompile and flash Grbl. This solution model is only 
      valid for this particular set of data. If the machine is altered, you will need to 
      perform this experiment again and regenerate a new model here. 
    
  OUTPUT: 
    The solver produces a set of values that define the piecewise fit and can be used by 
    Grbl to quickly and efficiently compute spindle PWM output voltage for a desired RPM.
    
    The first two are the RPM_MAX ($30) and RPM_MIN ($31) Grbl settings. These must be 
    programmed into Grbl manually or setup in defaults.h for new systems. Altering these 
    values within Grbl after a piece-wise linear model is installed will not change alter 
    model. It will only alter the range of spindle speed rpm values Grbl output. 
    
    For example, if the solver produces an RPM_MAX of 9000 and Grbl is programmed with 
    $30=8000, S9000 may be programmed, but Grbl will only produce the output voltage to run 
    at 8000 rpm. In other words, Grbl will only output voltages the range between 
    max(RPM_MIN,$31) and min(RPM_MAX,$30).
          
    The remaining values define the slopes and offsets of the line segments and the junction 
    points between line segments, like so for n_pieces=3:
          
      PWM_output = RPM_LINE_A1 * rpm - RPM_LINE_B1     [ RPM_MIN < rpm < RPM_POINT12 ]
      PWM_output = RPM_LINE_A2 * rpm - RPM_LINE_B2     [ RPM_POINT12 < rpm < RPM_POINT23 ]
      PWM_output = RPM_LINE_A3 * rpm - RPM_LINE_B3     [ RPM_POINT23 < rpm < RPM_MAX ]
      
    NOTE: The script solves in terms of PWM but the final equations and values are expressed 
    in terms of rpm in the form 'PWM = a*rpm - b'. 
  
  """
  
  from scipy import optimize
  import numpy as np
  
  # ----------------------------------------------------------------------------------------
  # Configure spindle PWM line fit solver
  
  n_pieces = 4 # Number of line segments used for data fit. Only 1 to 4 line segments supported.
  
  # Programmed 'S' spindle speed values. Must start with minimum useful PWM or 'S' programmed
  # value and end with the maximum useful PWM or 'S' programmed value. Order of the array must
  # be synced with the RPM_measured array below. 
  # NOTE: ** DO NOT USE DATA FROM AN EXISTING PIECEWISE LINE FIT. USE DEFAULT GRBL MODEL ONLY. **
  PWM_set = np.array([2,18,36,55,73,91,109,127,146,164,182,200,218,237,254], dtype=float)
  
  # Actual RPM measured at the spindle. Must be in the ascending value and equal in length 
  # as the PWM_set array. Must include the min and max measured rpm output in the first and 
  # last array entries, respectively.
  RPM_measured = np.array([213.,5420,7145,8282,9165,9765,10100,10500,10700,10900,11100,11250,11400,11550,11650], dtype=float)
  
  # Configure line fit points by 'S' programmed rpm or PWM value. Values must be between 
  # PWM_max and PWM_min. Typically, alter these values to space the points evenly between 
  # max and min PWM range. However, they may be tweaked to maximize accuracy in the places 
  # you normally operate for highly nonlinear curves. Plot to visually assess how well the 
  # solution fits the data.
  PWM_point1 = 20.0 # (S) Point between segments 0 and 1. Used when n_pieces >= 2.
  PWM_point2 = 80.0  # (S) Point between segments 1 and 2. Used when n_pieces >= 3.
  PWM_point3 = 150.0  # (S) Point between segments 2 and 3. Used when n_pieces = 4.
  
  # ----------------------------------------------------------------------------------------
  
  # Advanced settings
  
  # The optimizer requires an initial guess of the solution. Change value if solution fails.
  slope_i = 100.0;  # > 0.0 
  
  PWM_max = max(PWM_set) # Maximum PWM set in measured range
  PWM_min = min(PWM_set) # Minimum PWM set in measured range
  plot_figure = True # Set to False, if matplotlib is not available.
  
  # ----------------------------------------------------------------------------------------
  # DO NOT ALTER ANYTHING BELOW.
  
  def piecewise_linear_1(x,b,k1):
      return np.piecewise(x, [(x>=PWM_min)&(x<=PWM_max)], [lambda x:k1*(x-PWM_min)+b])
      
  def piecewise_linear_2(x,b,k1,k2):
      c = [b, 
           b+k1*(PWM_point1-PWM_min)]
      funcs = [lambda x:k1*(x-PWM_min)+c[0], 
               lambda x:k2*(x-PWM_point1)+c[1]]
      conds = [(x<PWM_point1)&(x>=PWM_min),
               (x<=PWM_max)&(x>=PWM_point1)]
      return np.piecewise(x, conds, funcs)
      
  def piecewise_linear_3(x,b,k1,k2,k3):
      c = [b, 
           b+k1*(PWM_point1-PWM_min),
           b+k1*(PWM_point1-PWM_min)+k2*(PWM_point2-PWM_point1)]
      funcs = [lambda x:k1*(x-PWM_min)+c[0], 
               lambda x:k2*(x-PWM_point1)+c[1],
               lambda x:k3*(x-PWM_point2)+c[2]]
      conds = [(x<PWM_point1)&(x>=PWM_min),
               (x<PWM_point2)&(x>=PWM_point1),
               (x<=PWM_max)&(x>=PWM_point2)]
      return np.piecewise(x, conds, funcs)
      
  def piecewise_linear_4(x,b,k1,k2,k3,k4):
      c = [b, 
           b+k1*(PWM_point1-PWM_min),
           b+k1*(PWM_point1-PWM_min)+k2*(PWM_point2-PWM_point1),
           b+k1*(PWM_point1-PWM_min)+k2*(PWM_point2-PWM_point1)+k3*(PWM_point3-PWM_point2)]
      funcs = [lambda x:k1*(x-PWM_min)+c[0], 
               lambda x:k2*(x-PWM_point1)+c[1],
               lambda x:k3*(x-PWM_point2)+c[2],
               lambda x:k4*(x-PWM_point3)+c[3]]
      conds = [(x<PWM_point1)&(x>=PWM_min),
               (x<PWM_point2)&(x>=PWM_point1),
               (x<PWM_point3)&(x>=PWM_point2),
               (x<=PWM_max)&(x>=PWM_point3)]
      return np.piecewise(x, conds, funcs)
  
  # ----------------------------------------------------------------------------------------
  
  print("\nCONFIG:")
  print("  N_pieces: %i" % n_pieces)
  print("  PWM_min: %.1f" % PWM_min)
  print("  PWM_max: %.1f" % PWM_max)
  if n_pieces > 1:
    print("  PWM_point1: %.1f" % PWM_point1)
  if n_pieces > 2:
    print("  PWM_point2: %.1f" % PWM_point2)
  if n_pieces > 3:
    print("  PWM_point3: %.1f" % PWM_point3)
  print("  N_data: %i" % len(RPM_measured))
  print("  PWM_set: ", PWM_set)
  print("  RPM_measured: ", RPM_measured)
    
  if n_pieces == 1:
    piece_func = piecewise_linear_1
    p_initial = [RPM_measured[0],slope_i]
  
    p , e = optimize.curve_fit(piece_func, PWM_set, RPM_measured, p0=p_initial)
    a = [p[1]]
    b = [ p[0]-p[1]*PWM_min]
    rpm = [ p[0],
            p[0]+p[1]*(PWM_point1-PWM_min)]
  
  elif n_pieces == 2:
    piece_func = piecewise_linear_2
    p_initial = [RPM_measured[0],slope_i,slope_i]
  
    p , e = optimize.curve_fit(piece_func, PWM_set, RPM_measured, p0=p_initial)
    a = [p[1],p[2]]
    b = [ p[0]-p[1]*PWM_min,
          p[0]+p[1]*(PWM_point1-PWM_min)-p[2]*PWM_point1]
    rpm = [ p[0],
            p[0]+p[1]*(PWM_point1-PWM_min),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_max-PWM_point1)]
  
  elif n_pieces == 3:
    piece_func = piecewise_linear_3
    p_initial = [RPM_measured[0],slope_i,slope_i,slope_i]
    
    p , e = optimize.curve_fit(piece_func, PWM_set, RPM_measured, p0=p_initial)
    a = [p[1],p[2],p[3]]
    b = [ p[0]-p[1]*PWM_min,
          p[0]+p[1]*(PWM_point1-PWM_min)-p[2]*PWM_point1,
          p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)-p[3]*PWM_point2]
    rpm = [ p[0],
            p[0]+p[1]*(PWM_point1-PWM_min),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)+p[3]*(PWM_max-PWM_point2) ]
  
  elif n_pieces == 4:
    piece_func = piecewise_linear_4
    p_initial = [RPM_measured[0],slope_i,slope_i,slope_i,slope_i]
    
    p , e = optimize.curve_fit(piece_func, PWM_set, RPM_measured, p0=p_initial)
    a = [p[1],p[2],p[3],p[4]]
    b = [ p[0]-p[1]*PWM_min,
          p[0]+p[1]*(PWM_point1-PWM_min)-p[2]*PWM_point1,
          p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)-p[3]*PWM_point2,
          p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)+p[3]*(PWM_point3-PWM_point2)-p[4]*PWM_point3 ]
    rpm = [ p[0],
            p[0]+p[1]*(PWM_point1-PWM_min),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)+p[3]*(PWM_point3-PWM_point2),
            p[0]+p[1]*(PWM_point1-PWM_min)+p[2]*(PWM_point2-PWM_point1)+p[3]*(PWM_point3-PWM_point2)+p[4]*(PWM_max-PWM_point3) ]
        
  else :
    print("ERROR: Unsupported number of pieces. Check and alter n_pieces")
    quit()
  
  print("\nSOLUTION:\n\n[Update these #define values and uncomment]\n[ENABLE_PIECEWISE_LINEAR_SPINDLE in config.h.]")
  print("#define N_PIECES %.0f" % n_pieces)
  print("#define RPM_MAX %.1f" % rpm[-1])
  print("#define RPM_MIN %.1f" % rpm[0])
  
  if n_pieces > 1:
    print("#define RPM_POINT12 %.1f" % rpm[1])
  if n_pieces > 2:
    print("#define RPM_POINT23 %.1f" %rpm[2])
  if n_pieces > 3:
    print("#define RPM_POINT34 %.1f" %rpm[3])
  
  print("#define RPM_LINE_A1 %.6e" % (1./a[0]))
  print("#define RPM_LINE_B1 %.6e" % (b[0]/a[0]))
  if n_pieces > 1:
    print("#define RPM_LINE_A2 %.6e" % (1./a[1]))
    print("#define RPM_LINE_B2 %.6e" % (b[1]/a[1]))
  if n_pieces > 2:
    print("#define RPM_LINE_A3 %.6e" % (1./a[2]))
    print("#define RPM_LINE_B3 %.6e" % (b[2]/a[2]))
  if n_pieces > 3:
    print("#define RPM_LINE_A4 %.6e" % (1./a[3]))
    print("#define RPM_LINE_B4 %.6e" % (b[3]/a[3]))
  
  print("\n[To operate over full model range, manually write these]")
  print("['$' settings or alter values in defaults.h. Grbl will]")
  print("[operate between min($30,RPM_MAX) and max($31,RPM_MIN)]")
  print("$30=%.1f (rpm max)" % rpm[-1])
  print("$31=%.1f (rpm min)" % rpm[0])
  
  if (PWM_min > 1)|(PWM_max<255):
    print("\n[Update the following #define values in cpu_map.h]")
    if (PWM_min >1) :
      print("#define SPINDLE_PWM_MIN_VALUE %.0f" % PWM_min)
    if PWM_max <255:
      print("#define SPINDLE_PWM_MAX_VALUE %.0f" % PWM_max)
  else:
    print("\n[No cpu_map.h changes required.]")
  print("\n")
  
  test_val = (1./a[0])*rpm[0] - (b[0]/a[0])
  if test_val < 0.0 :
    print("ERROR: Solution is negative at RPM_MIN. Adjust junction points or increase n_pieces.\n")
  
  if plot_figure:
    import matplotlib
    matplotlib.use("Agg")
    import matplotlib.pyplot as plt
    
    fig = plt.figure()
    ax = fig.add_subplot(111)
    xd = np.linspace(PWM_min, PWM_max, 10000)
    ax.plot(PWM_set, RPM_measured, "o")
    ax.plot(xd, piece_func(xd, *p),'g')
    plt.xlabel("Programmed PWM")
    plt.ylabel("Measured RPM")
    
    # Check solution by plotting in terms of rpm.
  #   x = np.linspace(rpm[0], rpm[1], 10000)
  #   ax.plot((1./a[0])*x-(b[0]/a[0]),x,'r:')
  #   if n_pieces > 1:
  #     x = np.linspace(rpm[1], rpm[2], 10000)
  #     ax.plot((1./a[1])*x-(b[1]/a[1]),x,'r:')
  #   if n_pieces > 2:
  #     x = np.linspace(rpm[2], rpm[3], 10000)
  #     ax.plot((1./a[2])*x-(b[2]/a[2]),x,'r:')
  #   if n_pieces > 3:
  #     x = np.linspace(rpm[3], rpm[-1], 10000)
  #     ax.plot((1./a[3])*x-(b[3]/a[3]),x,'r:')
  
    fig.savefig("line_fit.png")
  