[challenge-bot] / guide / challenge-bot.scm

;; tldr; AGPLv3+
;; copyright info at bottom

(document
 :title [challenge-bot]
 (toc)
 (chapter
  :title [mechanical]
  (p [let's build your robot!])
  (section
   :title [arduino to deck]
   (p [let's attach the arduino to the deck.])
   (subsection
    :title [required materials]
    (p [you will need the things in this picture.])
    (figure
     :legend "arduino to deck / required materials"
     (image :file
            "0-arduino-to-deck/0-required-materials.png"))
    (itemize
     (item [medical kit with bandages])
     (item [safety goggles])
     (item [drill bit \(we will determine size in a moment\)])
     (item [drill])
     (item [alan wrench])
     (item [wood block])
     (item [arduino])
     (item [#6-32x3/8\", four of them])
     (item [robot deck, the white thing with a grid of holes])))
   (subsection
    :title [first hole]
    (subsubsection
     :title [choosing drill bit]
     (p [the arduino comes with holes in it already, so we will make
             some choices around those holes.
             choosing the right drill bit depends on what job you are
             doing.
             right now, we are making holes for screws to hold the
             arduino to the deck.
             there are two constraints between the hole and screw.
             each hole needs to be big enough for the screw body to fit
             through it.
             the holes also need to be smaller than the screw's thread.
             since there are holes on the arduino already, the screw was
             chosen to match it.
             the screw was chosen so that the hole on the arduino was
             bigger than the screw body and smaller than its thread.
             we will choose the biggest drill bit that fits through the
             hole on the arduino, then use that to drill holes in the
             deck.])
     (p [here's a cross section of a screw in the deck])
     (figure :legend "screw cross section"
             (image :file
                    "0-arduino-to-deck/screw-cross-section.png"))
     (p [check])
     (enumerate
      (item
       [what would happen if the drill bit were larger than the
             screw thread?])
      (item
       [what would happen if the drill bit were smaller than the
             screw body?])))
    (subsubsection
     :title [inserting drill bit]
     (figure :legend "arduino to deck / insert bit"
             (image :file "0-arduino-to-deck/1-insert-bit.png"))
     (p [insert the drill bit into the teeth of the drill.
                insert it far enough that the teeth will clamp on the
                smooth part of the bit when they are tightened.])
     (figure
      :legend "arduino to deck / twist tighten drill teeth"
      (image
       :file "0-arduino-to-deck/2-twist-tighten-drill-teeth.png"))
     (p [while holding the drill bit, twist end of the drill to tighten
               the teeth.
               make sure that the teeth end up gripping the flat part of
               the drill bit.])
     (p [check])
     (enumerate
      (item
       [where should the teeth clamp down on the drill bit?])
      (item
       [what would happen if the teeth tightened on the recessed
             part of the drill bit?])))
    (subsubsection
     :title [holding drill]
     (p [hold the drill with one hand on the handle and trigger.
              put the other hand on the orange nozzle, before the
              black spinning part.]))
    (subsubsection
     :title [arduino placement]
     (p [the arduino should be placed as shown in this picture.])
     (figure :legend "arduino to deck / place arduino"
             (image :file "0-arduino-to-deck/3-place-arduino.png"))
     (p [here's a closeup])
     (figure :legend "arduino to deck / place arduino closeup"
             (image :file
                    "0-arduino-to-deck/4-place-arduino-closeup.png"))
     (p [the picture above shows where to place the arduino on the deck.
             the arduino should line up with the holes on the deck.
             this alignment line is highlighted in pink.
             on the arduino, there's a hole on the top left, between the
             orange reset button and black headers.
             the green circle shows where the hole is.
             the blue box encloses the arduino hole and two deck holes.
             place the arduino hole mid-way between the two
             deck holes.])
     (p [check])
     (enumerate
      (item
       [should the arduino be upside-down?])
      (item
       [what should the upper side of the arduino align with?])
      (item
       [why not place the arduino up along the left side of the
            robot?])))
    (subsubsection
     :title [drilling practice]
     (p [strength check])
     (itemize
      (item [put on safety goggles])
      (item [unplug drill])
      (item [hold drill in one hand])
      (item [point drill at the ground])
      (item [point drill at the wall]))
     (p [steps for drilling into wood block])
     (itemize
      (item [plug in the drill])
      (item [place the drill bit in position])
      (item [bring the drill up to full speed, and keep it at full
                   speed while lowering and raising the drill])
      (item [push down until the drill bit has passed through an inch
                  of the wood block])
      (item [keep the drill at full speed])
      (item [stop before the drill smashes into the wood block])
      (item [keep the drill at full speed by holding the trigger])
      (item [bring the drill straight back up])
      (item [hold the trigger down to keep the drill at full speed])
      (item [once the drill is back out of the hole, let go of the
                  trigger]))
     (p [check])
     (enumerate
      (item
       [should the drill be at full speed while the drill bit is
               going down into the wood and coming back up?])
      (item
       [how do you keep the drill at full speed?])
      (item
       [what would happen if the drill bit were not at full
             speed?])
      (item
       [what would happen if the drill were twisted sideways while
             the drill bit were in the wood?])))
    (subsubsection
     :title [drilling the first screw hole]
     (itemize
      (item [place the drill bit in position])
      (item [bring the drill up to full speed, and keep it full speed])
      (item [push down until the drill bit has passed through the
                  deck])
      (item [keep the drill at full speed])
      (item [stop before the drill smashes into the arduino])
      (item [keep the drill at full speed by holding the trigger])
      (item [bring the drill straight back up])
      (item [hold the trigger down to keep the drill at full speed])
      (item [once the drill is back out of the hole, let go of the
                  trigger]))
     (p [check])
     (enumerate
      (item
       [should the drill be at full speed while the drill bit is
               going down into the wood and coming back up?])
      (item
       [what would happen if the drill bit were not at full speed?])
      (item [how do you keep the drill at full speed?]))))
   (subsection
    :title [first screw]
    (subsubsection
     :title [fastening arduino to deck using #6-32x3/8\" screw]
     (p [the "#6" part of "#6-32x3/8\"" is how big around the bolt is.
             it is related to wire gauge.
             bigger numbers mean larger screws.
             smaller numbers means smaller screws.])
     (figure :legend "arduino to deck / #6-32 screw"
             (image :file "0-arduino-to-deck/6-32-screw.png"))
     (p [check])
     (enumerate
      (item
       [in the motor assembly, there are #4-40x1.25\" screws.
           are those fatter, thinner, or the same thickness as the
           #6-32x3/8\" screws?]))
     (p [the "32" part of "#6-32x3/8\"" is a measurement of how close
             the threads are to each other.
             this is related to the angle of the thread, which is also
             called pitch.
             it is a count of how many times the thread wraps around one
             inch of the screw body.])
     (p [the head is the flat part where some tool, like the alan
             wrench, can exert force to spin the screw.])
     (p [check])
     (enumerate
      (item [how many times will the thread wrap around one inch of
                 the screw body?])
      (item [what about 2 inches?
                  how many times will the thread wrap around two
                  inches of the screw body?])
      (item [where can a tool exert turning force on the screw?])))
    (subsubsection
     :title [fasten the arduino board to the deck]
     (p [first we'll put the screw into the deck just enough so the deck
               holds it in place.
               then we will hold the arduino up to the screw and finish
               tightening the screw down.
               with the screw partially in, we do not have hold it as
               rigidly while we are also holding the arduino and
               the deck.])
     (p [push the #6-32 screw into the deck from the underside.
              the underside is the brown side.
              at the same time, spin the 6-32 screw so it rotates
              clockwise while looking down on its head.
              twist until the tip of the screw is about to stick out on
              the top side of the deck.])
     (p [hold the arduino board flat to the deck and line up the arduino
              hole so the screw can come up through it.
              continue tightening the screw into the deck, spinning the
              same direction as before.
              tighten until the screw head touches the deck.
              do not continue tightening after that.])
     (p [the arduino should still be flat against the deck still, just
             as it was before tightening the screw.])
     (p [check])
     (enumerate
      (item [why do we insert the first screw partially before
                 holding up the arduino?])
      (item [which side of the deck is the top side?])))
    (subsubsection
     :title [assessment of the first screw]
     (itemize
      (item [,(bold [warning]), if you rotate the arduino board too
             much,you will unscrew it from the deck and you'll have to
             screw it back in.
             rotating a few degrees should be ok.])
      (item [does the arduino stay with the deck when the deck moves?])
      (item [can the arduino board still rotate a few degrees?]))))
   (subsection
    :title [second hole and screw]
    (subsubsection
     :title [arduino board move relative to deck]
     (p [without any screws, the arduino board can move independently of
                 the deck.
                 it can translate and rotate freely.
                 with the first screw, the arduino can rotate around one
                 point on the deck and can no longer translate much.])
     (p [the second screw limits rotation a lot.
             it also makes translation even more difficult.
             it might even be too small to be detectable by directly
             looking at it.])
     (p [to choose where the second hole and screw should go, we should
            keep in mind that the goal is to attach the deck to the
            arduino.
            this means minimizing rotation and translation.
            the picture below shows that the second hole should be as
            far as possible from the first hole, since that minimizes
            rotation.])
     (figure
      :legend "arduino to deck / keep holes far apart"
      (image
       :file "0-arduino-to-deck/keep-holes-far-apart.png")))
    (subsubsection
     :title [drilling and attaching second screw]
     (p [to drill the second hole, follow the same steps as drilling the
            first hole.
            hold the arduino down as before, and drill through the hole
            furthest away from the first hole.
            then insert and tighten the screw as before.])))
   (subsection
    :title [third and fourth hole and screw]
    (p [even though the arduino is pretty well attached with just 2
             screws, we will add a third and fourth.
             this gives practice drilling and tightening screws.
             it also keeps the arduino fixed even more rigidly.]))
   (subsection
    :title [assessment of arduino deck attachment]
    (itemize
     (item [you should now be able to grab the deck and shake it.
                the arduino should stay firmly in place while you do.])
     (item [the arduino should be close to but not touching an edge.])
     (item [there should be no warping on the arduino.
                  this could happen if the screws are too tight.]))))
  (section
   :title [breadboard]
   (p [next, let's attach other parts to the deck.
             we'll start with the breadboard.
             there are many ways to do this, but one handy approach is
             glue dots.
             glue dots can be placed easily, are good at attaching flat
             surfaces that directly touch and do not get much stress.])
   (figure :legend "breadboard to deck / required materials"
           (image
            :file "1-breadboard-to-deck/0-required-materials.png"))
   (p [for this section, we will need the deck with arduino attached,
           breadboard, and glue dots.])
   (figure :legend "breadboard to deck / video"
           (video
            :file "1-breadboard-to-deck/0-breadboard-to-deck.ogv"))
   (enumerate
    (item [take your breadboard out of its bag.])
    (item [peel the backing.])
    (item [put the shiny medal plate on the back.])
    (item [break 4 glue dots away from the rest.  put the rest back
                 into the bag.])
    (item [break off a glue dot from the group of 4, and peel away the
                 backing, exposing a sticky side.])
    (item [put the glue dot on one corner of the shiny side of the
               breadboard.
               make sure to push it down firmly.])
    (item [repeat for the other corners.])
    (item [put the breadboard on the center of the deck.
               position it so the black chip is on the right, and the
               blue line is up against the arduino.])
    (item [press firmly in each of the corners.]))
   (p [check])
   (enumerate
    (item [should the black chip be on the right or the left?])
    (item [how many glue dots should be on the breadboard?])))
  (section
   :title [battery packs]
   (subsection
    :title [leads]
    (subsubsection
     :title [strip]
     (p ["leads" are the wires coming out of the battery pack.
         prepare the leads of the batteries by stripping them and
         placing heat shrink on them.
         your battery packs are not attached to your deck yet,
         but that will be the next step.])
     (figure :legend "batteries / prepare leads / stripping"
             (video
              :file "2-batteries/0-prepare-leads/0-strip.ogv"))
     (enumerate
      (item (bold [do not pick up batteries by their leads!]))
      (item [strip the leads a tiny bit at a time.
                   keep stripping until a total of an inch is stripped.
                   the leads are made of tons of tiny wires that will
                   tear apart if too much insulation is stripped at
                   once.
                   wire made of a bunch of tiny wires
                   is "stranded wire".])
      (item [strip both leads of both batteries.])
      (item [then place heat shrink on every lead.
                  make sure the heat shrink is either clear or matches
                  the color of the lead.]))
     (p [check])
     (enumerate
      (item [should you pick up a battery by its leads?])
      (item [should you strip the leads a large amount at a time?])
      (item [what's the name of wires made of a bunch of tiny
                    wires?])))
    (subsubsection
     :title [wrap]
     (p [do the next 2 sections with just one lead at a time.
            wrap, then solder one battery lead before moving on to the
            next.
            wrap the stranded wire around a solid core wire, as shown
            in this video.])
     (figure :legend "batteries / prepare leads / wrap"
             (video
              :file "2-batteries/0-prepare-leads/1-wrap.ogv"))
     (p [the solid core wire is the stiff short wire.
             it is much easier to poke into the breadboard.])
     (p [check])
     (enumerate
      (item [why are we using a solid core wire?])))
    (subsubsection
     :title [solder]
     (p [do this next section and the previous with just one lead at a
            time.
            solder the stranded wire and solid core wire, as shown
            in this video.])
     (figure :legend "batteries / prepare leads / solder"
             (video
              :file "2-batteries/0-prepare-leads/2-solder.ogv"))
     (p [soldering is the process of joining 2 metal things with
                   solder.])
     (enumerate
      (item [use the helping hands to grab the wires and hold them in
                 place.])
      (item [clean off the tip of the soldering iron if it has been
                   sitting still for a while.
                   this cleans off corroded metal.])
      (item [apply some solder directly to the tip of the soldering
                   iron.
                   this creates a pool of solder on the tip.
                   we will use this to transfer heat to the wires.])
      (item [put the soldering iron up to the wires.
                 we want the wires to be hot enough to melt the
                 solder.
                 at the same time, poke the solder into the wire.
                 the solder will start melting and quickly spread to
                 hot parts of the wire.
                 there will be smoke.])
      (item [move the solder away, then move the iron away.]))
     (p [check])
     (enumerate
      (item [should the wires melt the solder?])
      (item [why should we clean off the tip of the soldering iron?])
      (item [why do we put more solder back on the tip of the iron?]))))
   (subsection
    :title [deck attachment]
    (subsubsection
     :title [motor battery pack attachment]
     (p [attach the motor battery pack to the robot deck.])
     (figure
      :legend "batteries / placement / motor pack"
      (video
       :file "2-batteries/1-placement/0-motor-battery-pack.ogv"))
     (p [we will use glue dots to attach the motor battery pack to the
            deck.
            the pack could be placed anywhere, but we will place it
            in the lower left side of the robot.
            this battery pack has 4 AA batteries in it.
            each battery has 1.5 volts difference between the positive
            and negative side.
            the batteries are connected in series.
            the total voltage difference for the whole battery pack is
            the sum of the individual voltages, which is 6 volts.])
     (enumerate
      (item [make sure you are placing dots on the side of the battery
                  pack without the on/off switch.])
      (item [peel off a glue dot for each of the corners of the
                  battery pack.])
      (item [when placing the battery pack, make sure the screw hole
                  aligns with a hole on the deck.]))
     (p [check])
     (enumerate
      (item [why place the glue dots on the side of the battery pack
                 without the on/off switch?])))
    (subsubsection
     :title [arduino battery pack attachment]
     (p [attach the arduino battery pack to the robot deck.])
     (figure
      :legend "batteries / placement / arduino pack"
      (video
       :file "2-batteries/1-placement/1-arduino-battery-pack.ogv"))
     (p [next, we will attach the arduino battery pack to the deck.
               again, the pack could be placed anywhere, but we will
               place it in the lower right side of the robot.])
     (enumerate
      (item [make sure you are placing dots on the side of the battery
                  pack without the on/off switch, just as before.])
      (item [peel off a glue dot for each end of the pack.])
      (item [when placing the battery pack, make sure the screw hole
                  aligns with a hole on the deck.]))
     (p [check])
     (enumerate
      (item [why align the screw with a hole on the deck?])))))
  (section
   :title [motors]
   (subsection
    :title [leads]
    (p [attach leads to the motors to supply the motor with power.])
    (figure
     :legend "motors / leads"
     (video
      :file "3-motor-assemblies/0-leads.ogv"))
    (enumerate
     (item [strip both the green and yellow wire on both ends.
                  strip one side only 1/8 inch.
                  strip the other side about 1/4 inch.])
     (item [use the end of the wire stripper to bend a hook in the wire.
                make this hook on the side of the wire with a smaller
                exposed section.])
     (item [do not bend the wire so that the exposed wire runs alongside
               the sheath.])
     (item [put the hooks through the tabs on the motor.
                make sure to place the green and yellow wire on the
                correct side of the motor.
                match the side of the motor that already has wires
                attached.
                wrap the rest of the wire around the motor in order to
                keep the wire from falling off.])
     (item [once the wire is in place, wrap solder around the motor tab
                 and wire.
                 heat up the solder, motor tab and wire with the
                 soldering iron.])
     (item [test the solder joint with the 9v battery.
                 touch the battery leads to the motor leads.
                 make sure the 9v battery is on.
                 if the motor moves, the solder joint is good!])
     (item [get section of electrical tape, roughly 100mm
                (about 4 inches).
                slide the middle of the tape under the wires.
                this tape will keep the solder joints away from the
                metal band around the motor.])
     (item [the zip tie will hold the wires to the motor.
                wrap the zip tie on the round part of the motor where
                it meets the square portion of the motor.
                this will provide mechanical support for the solder
                joints.
                once the zip tie is wrapped, use wire strippers to cut
                off the excess zip tie.])
     (item [cover the solder joint with hot glue.
                  this will further keep the solder joints from corroding
                  in the air's moisture.
                  it will also keep the joint safe from anything poking
                  in.]))
    (p [check])
    (enumerate
     (item [should the electrical tape go between the wires and the
                   metal band?])
     (item [are the motor tabs strong?])
     (item [what are we doing to reinforce the motor tabs mechanically?])
     (item [does hot glue make an electrical connection?])))
   (subsection
    :title [motor mount]
    (p [now let's attach the motor mount to the motor.])
    (subsubsection
     :title [angle bracket to motor mount]
     (p [first, attach the angle brackets to the motor mounts with
                #6-32x3/8 inch screws.])
    (figure
     :legend "motors / mount / angle bracket"
     (video
      :file "3-motor-assemblies/1-motor-mount/0-angle-brackets.ogv"))
    (p [if you cover up 2 of the holes on the motor mount, the
           remaining holes look like a surprised face.
           these are the holes to attach the angle brackets.
           make sure the angle brackets on one motor mount are attached
           in a mirror image to the other.])
    (p [check])
    (enumerate
     (item [should the motor mounts have angle brackets attached in
                   a mirror image fashion?])
     (item [why should the motor mounts have angle brackets attached in
                   a mirror image fashion?])))
    (subsubsection
     :title [motor mount to motor]
     (p [now attach the motor mount with angle brackets to the motor.])
     (figure
      :legend "motor / mount / mount to motor"
      (video
       :file
       "3-motor-assemblies/1-motor-mount/1-motor-mount-to-motor.ogv"))
     (p [we will attach the motor mount to the motor using #4 bolts.
            these screws are thinner than the #6 bolts we have used.
            to clamp down on the motor, we will use a #4 nut.
            the white side of the nut should face outward.
            this section of the nut will keep the nut from jiggling
            loose off the bolt during normal operation.
            the head of the #4 bolt is a philips head, so we will
            use a philips head driver for it.])
     (p [check])
     (enumerate
      (item [is the #4 bolt thicker or thinner than the #6?])
      (item [do you have a ratcheting socket wrench, or not?]))))
   (subsection
    :title [deck attachment]
    (p [now that the motor assemblies are together, we will attach them
            to the deck.])
    (figure
     :legend "motor / motor assembly to deck"
     (video
      :file "3-motor-assemblies/2-motor-assembly-to-deck.ogv"))
    (p [when attaching the motor assembly to the deck, be sure to push
             the assembly as far outward from the center of the robot
             as you can while tightening it down.
             this will give more clearance to the wheels of the robot
             so they do not rub the deck.])))
  (section
   :title [caster]
   (p [the caster will go at the back of the robot and provide a third
           point of contact for the robot, making it easier for it to
           balance.])
   (figure
    :legend "caster"
    (video :file "4-caster-to-deck.ogv"))
   (p [check])
   (enumerate
    (item [what would happen if the robot did not have a caster?])))
  (section
   :title [wheels]
   (p [now we will attach the wheels.
           this makes the motor movement transform into robot movement!])
   (figure
    :legend "wheel"
    (video :file "5-wheel-to-robot-assembly.ogv"))
   (p [check])
   (enumerate
    (item [does the robot's wheels scrape the deck?])
    (item [what would happen if the robot had no wheels?])
    (item [what does the tread do?])
    (item [what is  the tread?])
    (item [what kind of screw is used?])))
  (section
   :title [sonars]
   (p [we are almost done with mechanical assembly!
          this next step is to add the sonar sensors to the robot.
          sonar sensors are what the robot uses to detect distances.
          it sends out a signal, then listens for a response and
          keeps track of how long it takes.])
   (figure
    :legend "sonar sensors"
    (video :file "6-sonar-sensors-to-deck.ogv"))
   (p [check])
   (enumerate
    (item [are your sonar sensors pointy pins facing in toward the
               arduino?])
    (item [was it difficult to get the sonar into the holder?])
    (item [what would happen if it was easy to slip the sonar sensor
                into the sonar holder?]))))
 (chapter
  :title [wiring and software]
  (section
   :title [serial]
   (subsection
    :title [software on computer]
    (subsubsection
     :title [arduino])
    (subsubsection
     :title [fritzing]))
   (subsection
    :title [attach arduino and computer via cable])
   (subsection
    :title [debugging common connection problems])
   (subsection
    :title [arduino reset button]))
  (section
   :title [left sonar]
   (subsection
    :title [breadboard connectivity])
   (subsection
    :title [cable])
   (subsection
    :title [arduino headers])
   (subsection
    :title [sound cm per microsecond at sea level]))
  (section
   :title [both sonars]
   (subsection
    :title [breadboard power rail]
    (p [power rail can provide power to more than one device.])))
  (section
   :title [left motor]
   (subsection
    :title [arduino digital output])
   (subsection
    :title [quad half h bridge, aka motor controller])
   (subsection
    :title [motor battery]))
  (section
   :title [both motors]
   (subsection
    :title [analogWrite]))
  (section
   :title [untethered]
   (subsection
    :title [arduino battery])
   (subsection
    :title [off and on functions]))
  (section
   :title [follow]
   (subsection
    :title [same wiring as untethered])
   (subsection
    :title [set motor])
   (subsection
    :title [go])
   (subsection
    :title [determining speed]))
  (section
   :title [stay on table]
   (subsection
    :title [stop])
   (subsection
    :title [backup])
   (subsection
    :title [turn around]))))

;; Copyright 2016 daniel watson

;; This file is part of challenge-bot.

;; challenge-bot is free software: you can redistribute it and/or modify
;; it under the terms of the GNU Affero General Public License as
;; published by the Free Software Foundation, either version 3 of the
;; License, or (at your option) any later version.

;; challenge-bot is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU Affero General Public License for more details.

;; You should have received a copy of the GNU Affero General Public
;; License along with challenge-bot.  If not, see
;; <http://www.gnu.org/licenses/>.