Vanderbilt Aerospace Design Lab2017-01-11T22:36:06+00:00http://vadl.github.ioWilliam Emfinger, Dexter Watkinsemfinger@isis.vanderbilt.edu, dexter.a.watkins@vanderbilt.eduUsing the BBB's PRUs2016-09-18T00:00:00+00:00http://vadl.github.io/tutorial/2016/09/18/using-the-bbbs-prus
<h1 id="overview">Overview</h1>
<p>This post will detail instructions on using the BBB’s PRU. For now it
is mainly a conglomeration of other detailed writeups on the topic.</p>
<p><a href="http://www.righto.com/2016/08/pru-tips-understanding-beaglebones.html">Ken Shirriff’s Blog Post</a></p>
<p><a href="http://mythopoeic.org/bbb-pru-minimal/">Small Golden Sceptre PRU Hellow World</a></p>
<p><a href="https://www.element14.com/community/community/designcenter/single-board-computers/next-gen_beaglebone//blog/2013/05/22/bbb--working-with-the-pru-icssprussv2">Element14 Working with the PRU</a></p>
<p><a href="https://credentiality2.blogspot.com/2015/09/beaglebone-pru-gpio-example.html">Credentiality PRU Example</a></p>
<h1 id="compiling-on-the-pru">Compiling on the PRU</h1>
<p><a href="http://www.ti.com/tool/ccstudio-sitara">TI’s Code Composer Studio with PRU C Compiler</a></p>
<p><a href="http://software-dl.ti.com/codegen/non-esd/downloads/beta.htm">Barebones TI PRU C Compiler</a></p>
<p><a href="https://www.embeddedrelated.com/showarticle/603/using-the-c-language-to-program-the-am335x-pru">Barebones C Compiler walkthrough by Fabien Le Mentec</a></p>
new post2016-09-11T00:00:00+00:00http://vadl.github.io/2016/09/11/new-postRoss_weber2016-09-06T00:00:00+00:00http://vadl.github.io/2016/09/06/Ross_Weber<h2 id="more-about-me">More About Me!!!!!</h2>
<h1 id="interests">Interests</h1>
<h1 id="skills">Skills</h1>
<h1 id="experiences">Experiences</h1>
Introduction to Jimmy2016-08-31T00:17:00+00:00http://vadl.github.io/members/2016/08/31/introduction_to_jimmy<h1 id="interests">Interests</h1>
<ul>
<li>Fabrication of rocket components and assembly of subsystems and systems</li>
<li>Cold gas thruster payload development and testing</li>
<li>KSP simulation</li>
</ul>
<h1 id="skills">Skills</h1>
<ul>
<li>MATLAB data analysis</li>
<li>PTC Creo Pro/E</li>
<li>Aerodynamics (con-di nozzles, fluids, flight mechanics, etc.)</li>
<li>Rapid prototyping design tools (3D printers, drilling, soldering, etc.)</li>
</ul>
Paul Moore2016-08-30T23:55:00+00:00http://vadl.github.io/members/2016/08/30/Test_Conversion<h2 id="vehicle-safety-and-environment">Vehicle Safety and Environment</h2>
<h3 id="safety-officer">Safety Officer</h3>
<p>The Vanderbilt SL rocketry and safety mentor is Robin Midgett, a member of the National Association of Rocketry who holds Level 2 certification. In conjunction with Dexter (NAR Level 1) and Ben, our student Safety Officer, Robin will oversee the rocketry team to ensure safety precautions are taken during the design, construction, testing, and storage of all rocket materials and equipment. During the course of the year, other members of the Vanderbilt SL team may pursue various NAR certifications as well.</p>
Derek Phillips2016-08-30T21:57:00+00:00http://vadl.github.io/members/2016/08/30/Derek_Phillips<h1 id="vadl-experience">VADL Experience</h1>
<ul>
<li>
<p>Outreach - curriculum development, report writing, and logistical coordinating.</p>
</li>
<li>
<p>Shadowing the carbon-fiber layups and various other tasks from last year’s rocket construction</p>
</li>
</ul>
<h1 id="interests">Interests</h1>
<ul>
<li>
<p>Thruster & Rocket test facility: frictionless mount, external torque control, and data validation/thruster calibration between real life and KSP simulation.</p>
</li>
<li>
<p>Fabrication of thruster system, integration into rocket, and fabrication of rocket body</p>
</li>
<li>
<p>Report writing</p>
</li>
</ul>
<h1 id="relevant-skills">Relevant Skills</h1>
<ul>
<li>
<p>MATLAB: data analysis,</p>
</li>
<li>
<p>LabView: instrument control and automation</p>
</li>
<li>
<p>1d analysis of converging-diverging nozzle performance including off-design conditions (study abroad class on Thermal Machines)</p>
</li>
<li>
<p>Technical writing</p>
</li>
<li>
<p>Creo: 3D CAD, machine drawings, exploded views, bill of materials, etc</p>
</li>
<li>
<p>Currently taking machining, also work in the design studio and am comfortable with rapid prototyping, drilling, sawing, soldering, dremels, etc.</p>
</li>
</ul>
Paul Register2016-08-30T13:09:00+00:00http://vadl.github.io/members/2016/08/30/Paul_Register<h1 id="experience">Experience</h1>
<ul>
<li>
<p>NASA Ames Research Center</p>
<ul>
<li>
<p>Asteroid fragmentation modeling with emphasis on risk assessment</p>
</li>
<li>
<p>Publication in Icarus</p>
</li>
</ul>
</li>
</ul>
<h1 id="interests">Interests</h1>
<ul>
<li>
<p>Comprehensive simulation of rocket flight in MATLAB</p>
</li>
<li>
<p>Report oversight (overall editing/proofreading of reports)</p>
</li>
<li>
<p>Would be interested in learning CFD or getting more involved in the mechanical aspects</p>
</li>
</ul>
<h1 id="skills">Skills</h1>
<ul>
<li>
<p>MATLAB</p>
</li>
<li>
<p>Technical writing</p>
</li>
</ul>
Introduction to Brian Ramsey2016-08-30T12:55:00+00:00http://vadl.github.io/members/2016/08/30/brianramsey<h1 id="rad-aero-skills">Rad #Aero Skills</h1>
<ul>
<li>CAD (CREO)</li>
<li>Matlab, excel, lots of data analysis last two summers</li>
<li>Technical writing</li>
</ul>
<h1 id="interests-things-i-want-to-be-a-part-of-on-the-team">Interests, things I want to be a part of on the team</h1>
<ul>
<li>Carbon fiber molding</li>
<li>Cold gas thruster design & fabrication work</li>
<li>KSP simulations</li>
</ul>
Michael Gilliland’s Interests2016-08-30T12:51:00+00:00http://vadl.github.io/members/2016/08/30/Michael-Gilliland<p>Past Experience:</p>
<p>Cisco Systems - Unified Computing System Manufacturing Engineering Intern</p>
<p>SMU Biomedical Robotics and Instrumentation Lab Assistant (5 Yrs)
-Work on humanoid arm tremor-simulator, tremor-dampening orthotics, and robotically assembled steerable surgical cannula</p>
<p>VADL Specific Interests:</p>
<p>Electromechanical systems</p>
<p>Controls</p>
<p>Machining (Have previously taken Machining, experience on personal lathe and mill)</p>
<p>Optical sensing (Previous work with LiDAR and computer vision)</p>
Introduction to git2016-08-30T09:16:00+00:00http://vadl.github.io/tutorial/2016/08/30/introduction-to-git<h2 id="what-is-git">What is Git?</h2>
<p>Git is a version control system (VCS) which exists as a distributed
tree based repository. It’s used for storing and versioning documents
and code, and allows you to at any time retrieve any of the files from
any of the current or past versions of the repository. It also has
features like file locking to ensure that only one person at a time
can make edits to a file, automatic merging for when two users make
changes to the same file at the same time but don’t conflict with each
other, and assisted merging for when two users make changes to the
same part of the same file at the same time. Most importantly Git is
useful for never losing your work by not only backing it up in the
cloud but by also ensuring that you can always revert back to a
pervious version on a per-file/folder/repository basis.</p>
<h2 id="how-to-install-git">How to install Git</h2>
<p>If you’re working with <a href="http://www.github.com">Github</a>, which you
probably are, and you don’t want to learn command line interfaces,
which you probably don’t, then you should just simplify your life and
download <a href="https://desktop.github.com/">Github Desktop</a>. It’s
available for both Windows and OSX.</p>
<p>If you’re on Linux, or would rather learn how to use git from the
command line (which is generally faster once you get used to it), then
you should simply use Git.
<a href="https://git-scm.com/book/en/v2/Getting-Started-Installing-Git">Here</a>
is a good link which gives the basic instructions for installing Git
under Linux, OSX, and Windows.</p>
<h2 id="how-to-use-git">How to use Git</h2>
<p>Most of the time you’re using Git, you won’t notice it. That’s
because most of the time you’re simply working as usual, occasionally
commiting your changes and pushing them into the cloud to back them
up. However, before you can do any of that, you must have a Git
repository.</p>
<h3 id="creating-a-repository">Creating a repository</h3>
<p>The easiest way to make and host a backed-up accessible git repository
is through <a href="http://github.com">Github</a>. There (as a registered user,
free account) you can create your own repositories which are hosted at
<em>http://github.com/${user name}/${repository name}</em>. If you have are
part of an organization (or create one), you can also create a
repository under the organization which will be hosted at
<em>http://github.com/${organization name}/${repository name}</em>. For this
team, you should be a part of and use the VADL organization, so create
any related repositories (that your team members will be using as
well) in the VADL organization. Creating a repository is as easy as
pressing the button that says <em>New Repository</em> and giving it a name.
Generally you do want to click the box that says <em>Initialize this
repository with a README</em>, since that will allow you to immediately
start working on it.</p>
<h3 id="cloning-a-repository"><em>Cloning</em> a repository</h3>
<p>Once you’ve created a repository (or if someone else already has, and
you’ve been given access by them or through a shared organization),
you can <strong>clone</strong> the repository onto your computer, which downloads
the entire repository (and its history), compressed of course, into a
folder of your choosing.</p>
<h4 id="github-desktop">Github Desktop</h4>
<p>In Github Desktop, this is as simple as clicking in the upper left to
clone a new repository and selecting one of the available repositories
that it shows you (those are all the repositories to which you have
write access).</p>
<h4 id="git-console">Git console</h4>
<p>To clone a repository (whether or not you have write access) in git
console you have two options, shown here as examples:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone git@github.com:<span class="k">${</span><span class="nv">user</span><span class="p">/organization name</span><span class="k">}</span>/<span class="k">${</span><span class="nv">repository</span><span class="p"> name</span><span class="k">}</span> <span class="k">${</span><span class="nv">optional</span><span class="p"> folder name</span><span class="k">}</span>
</code></pre>
</div>
<p>and</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone https://github.com/<span class="k">${</span><span class="nv">user</span><span class="p">/organization name</span><span class="k">}</span>/<span class="k">${</span><span class="nv">repository</span><span class="p"> name</span><span class="k">}</span> <span class="k">${</span><span class="nv">optional</span><span class="p"> folder name</span><span class="k">}</span>
</code></pre>
</div>
<p>e.g.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>git clone git@github.com:vadl/agse
git clone git@github.com:vadl/agse AGSE_REPO
git clone https://github.com/vadl/agse
git clone https://github.com/vadl/agse.git
git clone https://github.com/vadl/agse AGSE_REPO
</code></pre>
</div>
<p>When using the <code class="highlighter-rouge">git@<url></code> syntax, it will use any configured ssh keys, otherwise it will ask you for login information.</p>
<h4 id="configuring-ssh-keys">Configuring SSH Keys</h4>
<p>If you were to clone a directory using the <code class="highlighter-rouge">git@<url></code> syntax without any prior setup, you will probably encounter the following:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>git clone git@github.com:vadl/agse
Cloning into <span class="s1">'agse'</span>...
The authenticity of host <span class="s1">'github.com (192.30.253.112)'</span> can<span class="s1">'t be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '</span>github.com,192.30.253.112<span class="s1">' (RSA) to the list of known hosts.
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
</span></code></pre>
</div>
<p>This is because git is trying to authenticate the session using something called <a href="https://wiki.archlinux.org/index.php/SSH_keys">ssh keys</a>. These kes take the form of a private and public key pair. Github needs access to the public key.</p>
<p>The first step is to generate a key pair. Type the following into the terminal:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>ssh-keygen
</code></pre>
</div>
<p>Accept the default key location and press enter twice when asked for a passphrase in order to leave it blank. It should look like the following:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>ssh-keygen
Generating public/private rsa key pair.
Enter file <span class="k">in </span>which to save the key <span class="o">(</span>/home/<username>/.ssh/id_rsa<span class="o">)</span>:
Enter passphrase <span class="o">(</span>empty <span class="k">for </span>no passphrase<span class="o">)</span>:
Enter same passphrase again:
Your identification has been saved <span class="k">in</span> /home/<username>/.ssh/id_rsa.
Your public key has been saved <span class="k">in</span> /home/<username>/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:gGJtSsV8BM+7w018d39Ji57F8iO6c0N2GZq3/RY2NhI username@hostname
The key<span class="se">\'</span>s randomart image is:
+---[RSA 2048]----+
| ooo. |
| oo+. |
| + +.+ |
| o + + E . |
| . . S . . <span class="o">=</span>.o|
| . + . . B+@o|
| + . oo<span class="k">*</span><span class="o">=</span>O|
| . ..+<span class="o">=</span>o+|
| <span class="nv">o</span><span class="o">=</span>ooo+|
+----[SHA256]-----+
</code></pre>
</div>
<p>Congratulations, you now have an ssh key pair residing in <code class="highlighter-rouge">/home/<username>/.ssh</code> titled <em>id_rsa</em> and <em>id_rsa.pub</em>.</p>
<p>The next step is to add the public key (<em>id_rsa.pub</em>) to your github profile. Navigate to your profile on <a href="https://github.com">github.com</a> and click on <em>edit profile</em>. Next, select <em>SSH and GPG keys</em> from the left-hand menu. Click <em>New SSH Key</em> on the top right of the screen, and give it a name (the name doesn’t matter). Next, go back to the terminal and enter the following command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat ~/.ssh/id_rsa.pub
</code></pre>
</div>
<p>You will see a mess of letters and numbers similar to what is below</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat ~/.ssh/id_rsa.pub
~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQD0s+l+kKCjbUtTjfgXRkKQ4V1YPAZ7XFZRYVFk1TyqAmQZvJAy9blU1ROtkcZQ6mMnwWOlu/xiJq8+HpTgrJ58tov4IdEGgNo5AC8z/3xaUfSP/k4g7IIhsf45MXuRbEckyrsv8CsEVasmf1ABzrA2n0aR7155/zB5W9o6fcvzEPPN1DxmltbEOVEeTaGU1Z9W9GhKC4IhbF1f2uCs9eWxYQmyuU9yQkdf0BijypcaxbQibCRUdEows0afYECK/QJxO6oLUsG+JKrKka/tqgULiuiYXoFm8Y0KWVQEswV41KjfGoRcHssW3yStRDqmy4al4SYZAAEHroqWDbM4VReB root@luthadel
</code></pre>
</div>
<p>Copy everything from <code class="highlighter-rouge">ssh-rsa</code> to the end of the random string (exlcuding any <code class="highlighter-rouge">user@host</code> at the end!). Paste this into the <em>Key</em> window in the github profile and you should have something similar to the following image.</p>
<p><img src="/images/git/github_ssh_keys.png" alt="sample profile" class="center-image" /></p>
<p>Now, cloning (and pushing/pulling) a repository will be sucessful! There is one more thing we can do though to make the process more streamlined in the future.</p>
<h3 id="git-global-config">Git Global Config</h3>
<p>We are going to set up a global username and email for git to use when pushing to github. This will prevent you have having to type in the information every time. Simply type the following into a terminal:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>git config --global user.name <span class="s2">"<Your Name Here>"</span>
git config --global user.email <span class="s2">"<Your Email Here>"</span>
</code></pre>
</div>
<p>That’s it, you done!</p>
<h3 id="working-as-usual">Working as usual</h3>
<p>Once you’ve cloned the repository, you can add files and edit existing files as you want, without having to use any interface or anything. Simply do your work as you normally do.</p>
<h3 id="commiting-your-work-locally"><em>Commiting</em> your work locally</h3>
<p>Every so often (generally when you’ve fininshed editing a file, or reached a stopping point you should commit your work so that it becomes part of the history of the repository. You generally want incremental changes as opposed to doing a lot of work and committing everything at once. The reason for this is in case you need to roll back (revert) some of the edits or in case you run into a merge conflict (e.g. if you and someone else touched the same file at the same time).</p>
<p>When you’re ready to commit you need to do three things:</p>
<ul>
<li>Update your local copy of the repository, this ensures that you’ve gotten any changes others have pushed to the repository since the last time you pulled or since when you cloned the repository:</li>
</ul>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git pull
</code></pre>
</div>
<p>Or in Github Desktop you simply <em>sync</em>.</p>
<ul>
<li>Tell git which files you’ve changed and want to commit:</li>
</ul>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git add <files to add>
</code></pre>
</div>
<p>Note: you can git add multiple times. On the console, use <code class="highlighter-rouge">git status</code> to have it tell you what you’ve committed and what you’ve changed but haven’t committed, and what you’ve added but not told git to version.</p>
<p>If you’re on Github Desktop, simply switch to the changes tab and select the files you want to add.</p>
<ul>
<li>Write a commit message and perform the commit:</li>
</ul>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git commit -m <span class="s2">"<commit message here>"</span>
</code></pre>
</div>
<p>Or if you’re on Github Desktop, just write the message in the text box when you add the files.</p>
<h3 id="pushing-your-work-to-the-cloud"><em>Pushing</em> your work to the cloud</h3>
<p>After you’ve edited files, pulled updates, add committed your changes you need to push those changes to the cloud.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>git push
</code></pre>
</div>
<p>or press the <em>sync</em> button in Github Desktop.</p>
<h3 id="pulling-others-work-from-the-cloud"><em>Pulling</em> others’ work from the cloud</h3>
<p>As stated above, pulling every so often to update your local copy of the repository is paramount to ensuring consistency.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git pull
</code></pre>
</div>
<h2 id="going-from-here">Going from here</h2>
<h2 id="further-references">Further references</h2>
<ul>
<li><a href="http://rogerdudler.github.io/git-guide/">Git Guide</a></li>
<li><a href="https://guides.github.com/">Using Github</a></li>
<li><a href="https://www.mutuallyhuman.com/blog/2012/06/22/a-git-walkthrough/">More information</a></li>
</ul>
Grady Lynch2016-08-30T09:16:00+00:00http://vadl.github.io/members/2016/08/30/Test_Post_Grady_Lynch<h1 id="interests">Interests</h1>
<ul>
<li>Rocket Fabrication</li>
<li>Machining</li>
<li>Optical Sensing</li>
</ul>
<h1 id="skills">Skills</h1>
<ul>
<li>SolidWorks</li>
<li>MATLAB</li>
<li>Familiar with C++ and ROS</li>
</ul>
Arthur Binstein2016-08-30T00:00:00+00:00http://vadl.github.io/members/2016/08/30/arthur-binstein<h2 id="interests">Interests</h2>
<ul>
<li>Space, especially the private space industry</li>
<li>Renewable energy technology</li>
<li>Smart and clean cities</li>
</ul>
<h2 id="experiences">Experiences</h2>
<ul>
<li>Manufacturing intern</li>
<li>Research assistant at STORM lab</li>
<li>Digital electronics</li>
<li>Built documentation using Sphinx</li>
<li>TinyOS programming</li>
</ul>
<h2 id="hopes-and-dreams-for-rocket-team">Hopes and dreams for Rocket team</h2>
<ul>
<li>CFD guy</li>
<li>Electronic system integration</li>
<li>Learn more about machining</li>
<li>Learn more about aero-thermodynamics</li>
</ul>
Getting a part from SolidWorks to KSP2016-07-31T00:00:00+00:00http://vadl.github.io/ksp/2016/07/31/getting-a-part-from-solidworks-to-ksp<p>This post will detail the process needed to get from a solidworks model of a park to a basic ksp .mu file</p>
<h1 id="required-programs">Required Programs</h1>
<ol>
<li>SolidWorks (Tested with 2014, later versions might not apply)</li>
<li><a href="http://www.solidsmack.com/resources/free-solidworks-obj-export-macro/">SolidWorks OBJ Conversion Macro</a></li>
<li><a href="https://unity3d.com/get-unity/download/archive">Unity 5.3.5f1</a></li>
<li>Kerbal Space Program (At least 1.1.3)</li>
<li><a href="http://forum.kerbalspaceprogram.com/index.php?/topic/135228-parttools-for-ksp-112/">Kerbal Part Tools</a> (It states this is part tools for 1.1.2, it is still valid for 1.1.3)</li>
</ol>
<h1 id="overview">Overview</h1>
<p>This process can be broken up into two steps. Getting from Soldworks
to Unity, and then getting from Unity to KSP. The first step is simply
a matter of exporting to a file format readable by unity, namely a
.obj file. The second step involves some more detailed work setting up
the part model, textures, and placing relevant coordinate frames.</p>
<h1 id="setting-up-unity">Setting up Unity</h1>
<p><em>This section needs to be verified, steps may have changed</em></p>
<ol>
<li>Open Unity, create a new project</li>
<li>Copy the entire Part Tools folder into the unity project’s assets folder</li>
<li>A “Tool” menu should now be available in the unity toolbar. Click Tools»KSP Part Tools and point to the GameData folder of a vanilla version of KSP (no mods).</li>
<li>Go into the Part Tools folder in Assets and double click PartTools_AssetBundles, click import.</li>
<li>Should now be set up?</li>
</ol>
<h1 id="getting-from-solidworks-to-unity">Getting from SolidWorks to Unity</h1>
<ol>
<li>Make a solidworks part.</li>
<li>Run the SW OBJ exporter macro</li>
<li>Open a unity project that is already set up for KSP</li>
<li>Drag the entire obj folder created via the macro into the assets pane (both .obj and .mtl)</li>
</ol>
<h1 id="getting-from-unity-to-ksp">Getting from Unity to KSP</h1>
<ol>
<li>Navigate to the material file in Assets and change the shader to a ksp shader</li>
<li>Add a texture. As an example: Drag a background texture from Squad/Kspedia/backgrounds to the texture panel of the material file</li>
<li>Create an empty game room under Hierarchy</li>
<li>Under inspector (with the game room selected) click Add Component»KSP»PartTools</li>
<li>Add model name and file path to write (example: GitHub/ksp-rocket-model/VADL/Parts/XXX/name)</li>
<li>Drag obj model into the game room</li>
<li>Select the game object. In the toolbar, go to Component»Physics»Mesh Collider.Point the mesh collider’s mesh to the model mesh, make sure convec mesh is checked.</li>
<li>Click write in Part Tool component to make the .mu file</li>
</ol>
<h1 id="adding-coordinate-transforms">Adding coordinate “Transforms”</h1>
<p>Some modules require coordinate frames to know where to apply a force or otherwise act. For example, a motor part needs to specify where thrust is applied.</p>
<h2 id="adding-a-thrust-transform">Adding a thrust transform</h2>
<ol>
<li>In unity, add a game object <em>under</em> the model’s game object (as a child)</li>
<li>Set the z direction (blue arrow) pointing in the direction of thrust</li>
<li>name the object “thrustTransform” and reference in in the .cfg file’s ModuleEngineFX module</li>
</ol>
<h2 id="adding-rcs-transform">Adding RCS transform</h2>
<ol>
<li>make a transform (unity game obj, see above section) for <em>each</em> thrust vector of the rcs system.</li>
<li>Thrust is in the <em>positive y</em> direction.</li>
<li>Name all transforms the same name so that onlyh one RCS module is needed in the .cfg file.</li>
</ol>
<h1 id="center-of-mass">Center of Mass</h1>
<p>Set the coordinates of the model object in unity so that the model’s Center of Mass is at the origin</p>
Setting Up the BeagleBone Black's GPIO Pins2016-07-29T07:27:00+00:00http://vadl.github.io/beagleboneblack/2016/07/29/setting-up-bbb-gpio<p>This post will detail how to set up the BBB’s GPIO pins. General
Purpose Input/Output (GPIO) pins are special in that they can be
configured at runtime to perform in a variety of ways, ranging from
simple i/o to serial interfaces to specialized encoder readings. While
the BBB supports up the 69 gpio pins, in reality the majority of the
pins are being used by onboard system processes such as the board’s
HDMI and LCD abilities. This post will detail the steps necessary to
take advantage of these otherwise inaccessible pins, as well as
configure a gpio pin to suit the user’s needs.</p>
<h2 id="linux-kernel-version">Linux Kernel Version</h2>
<p>This guide assumes the user’s BBB is running <em>Linux Kernel 4.1.15</em>. If
an earlier version is used, such as <em>3.8.X</em>, then abundant information
on configuring the BBB can be found through google and the procedures
listed in this guide will probably not work.</p>
<h2 id="bbb-headers-and-pinout">BBB Headers and Pinout</h2>
<p>The BBB has two 23 pin columns on each side of the board, for
a total of 92 pins available to the user. The right header is
designated as P8 while the left is designated P9. Pay careful
attention to the orientation of the BBB in reference to the pinout
numbers, else you risk mis-wiring the board and potentially causing
irreversible damage. Physical pins are numbered in the following
manner, <code class="highlighter-rouge">PX_Y</code>, where <code class="highlighter-rouge">X</code> is the header where the pin is located (8 or
9) and <code class="highlighter-rouge">Y</code> is the location of the pin with that header. Pins <em>P8_1</em>
and <em>P9_1</em> are located at the top right of each header. Notice that
the left column of each header are all the odd pins while the right
column of each header are all the even pins.</p>
<p><img src="/images/bbb/bbb_headers.png" alt="BBB Headers" class="center-image" /></p>
<p>As seen in the graphic, the first and last rows of pins are dedicated
to nets such as <em>DGND</em>, <em>VDD_3V3</em> (3.3V Output), <em>VDD_5v</em> (5V
Output), and system power/reset. The rest of the pins are configurable
in software, as will be detailed later in this post. The labels on the
graphic show the <em>default mode</em> of the pins. Not all pins are able to
be used as GPIO’s immediately. Systems such as the LCD and HDMI
drivers take priority to these pins. A more detailed view of the BBB’s
header’s and pin usage can be seen in the graphics below</p>
<p><img src="/images/bbb/P8Header.png" alt="P8 Header" class="center-image" />
<img src="/images/bbb/P9Header.png" alt="P9 Header" class="center-image" /></p>
<h3 id="gpio-numbering-scheme">GPIO Numbering Scheme</h3>
<p>The gpio pins of the bbb are grouped into 3 groups of 32: <em>GPIO0</em>,
<em>GPIO1</em>, and <em>GPIO2</em>. An individual pin can be refered to using the
convention <code class="highlighter-rouge">GPIOX_Y</code> where <code class="highlighter-rouge">X</code> is its gpio register and <code class="highlighter-rouge">Y</code> is its
number within that register. <em>However, all references to a particular
pin made in software instead uses its absolute pin number!</em> A gpio’s
<em>absolute</em> pin number is calculated in the following manner: <code class="highlighter-rouge">Z =
32*X + Y</code> where <code class="highlighter-rouge">X</code> is again the gpio register and <code class="highlighter-rouge">Y</code> is the position
within that register.</p>
<p>i.e. GPIO2_24 is <code class="highlighter-rouge">32*2+24</code>, making it GPIO_88. <em>If this pin were to be
referenced anywhere in software, the user would use the number 88, not
24</em>!</p>
<h3 id="overloaded-pins">Overloaded Pins</h3>
<p>Additional scrutiny of the above header pin layouts shows all the
possible uses of each individual pin. Any pin highlighted in red is a
pin that is inaccessible for use as a gpio pin by default, see the
notes column for it’s initial allocation. As an example, P8_28, aka
GPIO2_24, aka GPIO_88, is by default allocated to the
<code class="highlighter-rouge">nxp_hdmi_bonelt_pins</code> group. While it is overloaded in this capacity,
no other use can be made of this pin. Multiple modes are available for
each pin, and setting these modes wil be discussed in a later section.</p>
<h3 id="recap-of-numbering-schemes">Recap of Numbering Schemes</h3>
<p>As a recap, <em>each gpio pin on the BBB has three different numbering schemes associated with it!</em></p>
<ol>
<li>The physical pin location, in the form of <code class="highlighter-rouge">PX_Y</code> (P8_28)</li>
<li>The gpio name, in the form of <code class="highlighter-rouge">GPIOX_Y</code> (GPIO2_24)</li>
<li>The gpio number, in the form of <code class="highlighter-rouge">32*X + Y</code> (88)</li>
</ol>
<p>Only the last scheme, the gpio number, is used in software!</p>
<h2 id="configuring-accessible-gpio-pins">Configuring Accessible GPIO Pins</h2>
<p>Once a GPIO pin is accessible (either by default or by configuring a
device tree overlay as detailed below), it is very easy to intereact
with it directly from the terminal. First, simply for ease of life,
enter the following command to temporarily switch to root for this
example.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>sudo su
</code></pre>
</div>
<p>We interact with BBB pins via a set of files that are read/written
to. To reach the directory where these files are located, enter the
following.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">cd</span> /sys/class/gpio
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">echo </span>27 > <span class="nb">export</span>
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">cd </span>gpio27
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">echo </span>out > direction
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat value
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">echo </span>1 > value
</code></pre>
</div>
<h3 id="access-using-c-library">Access using C++ library</h3>
<p>The C++ library can be found <a href="github.com/rosmod/lib-bbbgpio">here.</a></p>
<div class="language-c++ highlighter-rouge"><pre class="highlight"><code><span class="cp">#include "gpio.h"
</span><span class="o">~~~</span>
<span class="o">~~~</span>
<span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">pin</span> <span class="o">=</span> <span class="mi">27</span><span class="p">;</span>
<span class="n">gpio_export</span><span class="p">(</span><span class="n">pin</span><span class="p">);</span>
<span class="n">gpio_set_dir</span><span class="p">(</span><span class="n">pin</span><span class="p">,</span><span class="n">OUT</span><span class="p">);</span>
<span class="n">gpio_set_value</span><span class="p">(</span><span class="n">pin</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
</code></pre>
</div>
<h2 id="accessing-inaccessible-pins">Accessing Inaccessible Pins</h2>
<p>Before going into the details of configuring inaccessible pins, it is
necessary to briefly go over the inner workings of the BBB and touch
on concepts such as pin modes, the device tree and its overlays, and
how to interact with it.</p>
<h3 id="pin-modes">Pin Modes</h3>
<p>As seen in the above graphics detailing the P8 and P9 headers, each
pin can be configured to one out of 8 possible modes. For our
purposes, it is important to note that mode7 is always the GPIO
configuration for every pin.</p>
<p>The pin mode for any given pin is stored in 7 bits using the following convention.</p>
<p><img src="/images/bbb/GPIO_Bits.png" alt="GPIO_Bits" class="center-image" /></p>
<p>Notice the example configurations under the table. The bits values are
listed in Hexadecimal form, so that the two digits following “0x”
contain the values of all 7 bits. The last digit of the pair contains
the values of bits 0,1,2, and 3. As such, in order to be in mode7
(GPIO) bits 0,1, and 2 are all 1, giving a possible value of either 7
or F for the last hex digit. (Binary of either 0111 or 1111). The
first digit of the pair contains the values of bits 4,5, and 6 (with
the most significant bit being a constant 0). If the pin is configured
as an output, then the possible values of this bit are 0 and 1 (0000
and 0001) depending on if pull down or pull up is selected. If the pin
is an input, the possible values are 2 and 3 (0010 and 0011), again
depending on the pullup/down setting</p>
<p>The pin mode of each pin is configured in what is called a device tree
overlay, which will be discussed in detail in a later section.</p>
<h3 id="device-tree">Device Tree</h3>
<p><a href="https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview">Here</a>
is a good overview of what exactly the device tree is. <em>BEWARE, THIS
LINK IS for the 3.8 KERNEL AND IS NO LONGER COMPLETELY ACCURATE!</em></p>
<p>The Linux Device tree controls the configuration of pins: mux mode,
direction, pullup/pulldown, etc. It is a generic, standardized way of
dealing with constantly updating hardware configurations. In short, it
describes the hardware in a system. It is the linux version of ARM
board files.</p>
<p>The device tree is compiled into a <code class="highlighter-rouge">.dtb</code> file that is then loaded
upon the kernel’s startup. All specified pins and peripherals are
loaded and configured for use in the system.</p>
<h3 id="cape-manager-and-device-tree-overlays">Cape Manager and Device Tree Overlays</h3>
<p>As mentioned in the previous section, the device tree is loaded when
the kernel starts. It would be a very long and tedious process if, in
order to make any changes to the device tree, one were required to
modify the device tree, recompile it, and restart the device. Luckily,
the BBB’s cape manager comes to the rescue. The cape manager allows
the modification of parts of the device tree <em>at runtime</em> by loading
<em>overlays</em> that enable peripherals or mux pins to a specific function.</p>
<p>To see what device overlays are currently loaded on the device:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat /sys/devices/platform/bone_capemgr/slots
</code></pre>
</div>
<p>As an example, one might see the following:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">root@node31:~# </span>cat /sys/devices/platform/bone_capemgr/slots
0: PF---- -1
1: PF---- -1
2: PF---- -1
3: PF---- -1
4: P-O-L- 0 Override Board Name,00A0,Override Manuf,BB-ADC
5: P-O-L- 1 Override Board Name,00A0,Override Manuf,gpio_88
</code></pre>
</div>
<p>This shows that two overlays, <em>BB-ADC</em> and <em>gpio_88</em>, have been loaded by the cape manager.</p>
<p>In order to check if an overlay has successfully changed the pins
modes of the target pins, utilize the following commands:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat /sys/kernel/debug/pinctrl/44e10800.pinmux/pins
</code></pre>
</div>
<p><code class="highlighter-rouge">/sys/kernel/debug/pinctrl/44e10800.pinmux/pins</code> will provide the pin
number, the pin’s physical memory address, and the current mode to
which the pin has been muxed.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>cat /sys/kernel/debug/pinctrl/44e10800.pinmux/pingroups | less
</code></pre>
</div>
<p><code class="highlighter-rouge">/sys/kernel/debug/pinctrl/44e10800.pinmux/pingroups</code> provides a list of all “claimed” pins, such as pins that are configured and reserved via overlays.</p>
<h3 id="dtc-and-compiling-custom-overlays">DTC And Compiling Custom Overlays</h3>
<p>In order to make custom overlays, it in necessary to install the device
tree overlay compiler made and maintained by Robert Nelson. It can be
found at
<a href="https://github.com/beagleboard/bb.org-overlays">https://github.com/beagleboard/bb.org-overlays</a>. For
ease of use, we have forked the current version at
<a href="https://github.com/VADL/bb.org-overlays">https://github.com/VADL/bb.org-overlays</a>,
so that as long as you are running the <em>4.1.15</em> kernel, compatibility
is not an issue.</p>
<p>To install the compiler, perform the following steps.</p>
<ol>
<li>clone the dtc repo</li>
</ol>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>git clone https://github.com/vadl/bb.org-overlays
<span class="nb">cd</span> ./bb.org-overlays
</code></pre>
</div>
<ol>
<li>Run the dtc-overlay script</li>
</ol>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>./dtc-overlay.sh
</code></pre>
</div>
<p>After installation, the dtc compiler can be called on a .dts file to
produce the corresponding .dtbo overlay file. For an example overlay
called <em>sample_overlay.dts</em>:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>dtc -O dtb -o /lib/firmware/sample_overlay-00A0.dtbo -b 0 -@ sample_overlay.dts
</code></pre>
</div>
<p>Be sure to put the new .dtbo file into <code class="highlighter-rouge">/lib/firmware</code> so that it is
visible to the BBB os. <em>ALWAYS APPEND ‘-00A0’ TO THE END OF A DTBO
FILE. THIS IS NECESSARY FOR THE FILE TO BE LOADED PROPERLY BY THE CAPE
MANAGER!</em></p>
<p>One minor yet crucial tidbit of knowledge to remember is that the overlay
name cannot exceed 14 characters. If this limit is exceeded then it
will not be able to be enabled by the cape manager.</p>
<p>To enable the overlay, type the following</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nb">echo </span>sample_overlay > /sys/devices/platform/bone_capemgr/slots
</code></pre>
</div>
<table>
<tbody>
<tr>
<td>Note that the name of the cape in this command is just sample_overlay, not sample</td>
<td>_overlay.dtbo</td>
</tr>
</tbody>
</table>
<p>To set the overlay to enable at boot, add the cape name in <code class="highlighter-rouge">/etc/default/capemgr</code></p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="nv">cape</span><span class="o">=[</span>comma delimited cape names]
</code></pre>
</div>
<p>Documentation on this <a href="http://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Loading_custom_capes">can be found here</a></p>
<h3 id="disabling-default-overlays">Disabling Default Overlays</h3>
<h3 id="enabling-and-disabling-custom-overlays">Enabling and Disabling Custom Overlays</h3>
<h2 id="related-concepts">Related Concepts</h2>
<h3 id="pru">PRU</h3>
<p>Reading and writing the gpio pins through the file system as detailed
above is a relatively slow process, capable of read/write frequencies
in the low hundreds of Hz. An alternative is to utilize the BBB’s built in
Programmable Realtime Units (PRU’s). PRU’s are independent units
completely separate from the BBB OS, and can allow I/O at up to 20
MSPS. While this guide does not detail how to use a PRU, don’t forget
it exists!</p>
<p><a href="https://github.com/beagleboard/am335x_pru_package">A GitHub repo supporting PRU use can be found here</a></p>
<p>Ken Shirrif has a blog post on the PRU <a href="http://www.righto.com/2016/08/pru-tips-understanding-beaglebones.html">here</a></p>
<h3 id="analog-io">Analog I/O</h3>
<h3 id="serial-and-uart-communication">Serial and UART Communication</h3>
<h2 id="links">Links</h2>
<p>A writeup about BBB Overlays and the cape manager can be found <a href="http://www.thing-printer.com/cape-manager-is-back-baby/">here</a></p>
<p>Ken Shirrif’s blog has a great post on the <a href="http://www.righto.com/2016/08/the-beaglebones-io-pins-inside-software.html">BBB GPIO</a></p>
<p>In addition to providing many of the graphics used in this document,
<a href="http://exploringbeaglebone.com/">Derek Molly has extensive documentation on all things BBB</a></p>
Introduction to LaTeX2016-07-11T09:18:00+00:00http://vadl.github.io/2016/07/11/introduction-to-latex<h2 id="what-is-latex">What is LaTeX?</h2>
<p>LaTeX is a tool for writing text without specifying how the text
should be laid out on a page and formatted. Normally, when text is
entered into a word processing document and saved, the layout of the
text, the style of the text, and the formatting of any tables,
figures, headings, etc. are all stored with the text and are
inseparable from the text itself.</p>
<p>So where is the formatting stored? The anser is the style file
(<code class="highlighter-rouge">.sty</code>) and its associated class files. These files are text
independent (i.e. they contain no text themselves that will wind up in
the final document. By swapping out the style/class files, you can
take the same LaTeX files and render a completely differently looking
document (e.g. presentation, book chapter, two column paper, thesis,
etc.)</p>
<p>Since you may want to re-use text between documents (and
figures/tables), you do not want to tightly couple the formatting of
the text with the text itself. Additionally (and most importantly) the
formatting and layout are not touched at all when editing the text, so
users are free to write and let the style file take care of all the
formatting.</p>
<p>Additionally, certain things like references (to figures, sections,
etc.), figure/table numbers, and citations are simpler and easier to
manage (i.e. they don’t ever change and you can be certain they’re
up-to-date).</p>
<p>Finally, LaTeX is also useful because you can include one file inside
other files. This allows you to break each section or chapter of a
long document up into separate files. This feature becomes especially
useful when collaborating with others on the same document since you
can more easily handle simultaneous working (since generally two
people will not be writing in the same text at the same time). Again,
even if there is a conflict and two people need to merge their text,
the text is <em>all</em> they need to merge; there will be no formatting
conflicts at all.</p>
<h2 id="how-to-install-latex">How to install LaTeX</h2>
<h3 id="windows">Windows</h3>
<h3 id="linux">Linux</h3>
<h3 id="osx">OSX</h3>
<h2 id="how-to-use-latex">How to use LaTeX</h2>
<h3 id="writing-latex">Writing LaTeX</h3>
<p>Writing LaTeX is for the most part the same as writing regular text
because that is all it is. Where things change a little bit is when
you want to enter mathematical equations, references, or citations.</p>
<h4 id="converting-from-markdown-into-latex">Converting from Markdown into LaTeX</h4>
<h3 id="compiling-latex-into-pdf">Compiling LaTeX into PDF</h3>
<h3 id="installing-packages">Installing Packages</h3>
<h3 id="how-to-include-references">How to include references</h3>
<p>Anywhere you have a <code class="highlighter-rouge">\label{label_name}</code>, e.g.</p>
<div class="language-latex highlighter-rouge"><pre class="highlight"><code><span class="k">\label</span><span class="p">{</span>simple<span class="p">_</span>label<span class="p">}</span>
<span class="k">\label</span><span class="p">{</span>sec:fluid<span class="p">_</span>dynamics<span class="p">}</span>
<span class="k">\label</span><span class="p">{</span>fig:fluid<span class="p">_</span>flow<span class="p">}</span>
<span class="k">\label</span><span class="p">{</span>table:experimental<span class="p">_</span>results<span class="p">}</span>
</code></pre>
</div>
<p>in any of your documents, you can easily reference them using that
same label, e.g.</p>
<div class="language-latex highlighter-rouge"><pre class="highlight"><code>Object <span class="k">\ref</span><span class="p">{</span>simple<span class="p">_</span>label<span class="p">}</span>
Section <span class="k">\ref</span><span class="p">{</span>sec:fluid<span class="p">_</span>dynamics<span class="p">}</span>
Figure <span class="k">\ref</span><span class="p">{</span>fig:fluid<span class="p">_</span>flow<span class="p">}</span>
Table <span class="k">\ref</span><span class="p">{</span>table:experimental<span class="p">_</span>results<span class="p">}</span>
</code></pre>
</div>
<h3 id="how-to-include-citations">How to include citations</h3>
<p>Assuming you have a bibliography file (<code class="highlighter-rouge">.bib</code>), that has references of
the form:</p>
<div class="language-latex highlighter-rouge"><pre class="highlight"><code>@article<span class="p">{</span>fractionated<span class="p">_</span>spacecraft,
tite=<span class="p">{</span>Assessing the fractionated spacecraft concept<span class="p">}</span>,
author=<span class="p">{</span>Mathieu, Charlotte and Wiegel, AL<span class="p">}</span>,
journal=<span class="p">{</span>AIAA Paper<span class="p">}</span>,
volume=<span class="p">{</span>7212<span class="p">}</span>,
year=<span class="p">{</span>2006<span class="p">}</span>
<span class="p">}</span>
@book<span class="p">{</span>fundamentals<span class="p">_</span>astrodynamics,
title=<span class="p">{</span>Fundamentals of Astrodynamics<span class="p">}</span>,
author=<span class="p">{</span>Bate, R.R. and Mueller, D.D. and White, J.E.<span class="p">}</span>,
isbn=<span class="p">{</span>9780486600611<span class="p">}</span>,
lccn=<span class="p">{</span>73157430<span class="p">}</span>,
series=<span class="p">{</span>Dover Books on Aeronautical Engineering Series<span class="p">}</span>,
year=<span class="p">{</span>1971<span class="p">}</span>,
publisher=<span class="p">{</span>Dover Publications<span class="p">}</span>
<span class="p">}</span>
</code></pre>
</div>
<p>then you can cite them anywhere in your documents as:</p>
<div class="language-latex highlighter-rouge"><pre class="highlight"><code><span class="k">\cite</span><span class="p">{</span>fundamentals<span class="p">_</span>astrodynamics<span class="p">}</span> talks about the fundamentals of
astrodynamics. More recently, <span class="k">\cite</span><span class="p">{</span>fractionated<span class="p">_</span>spacecraft<span class="p">}</span> discussed
and analyzed the concepts of fractionated spacecraft flying in
formation.
</code></pre>
</div>
<h2 id="going-from-here">Going from here</h2>
<h2 id="further-references">Further references</h2>
<ul>
<li><a href="http://en.wikibooks.org/wiki/LaTeX">LaTeX Wiki 1</a></li>
<li><a href="http://latex.wikia.com/wiki/Main_Page">LaTeX Wiki 2</a></li>
</ul>
Dustin Howser2016-07-08T00:00:00+00:00http://vadl.github.io/members/2016/07/08/Dustin Howser
<h1 id="interests">Interests</h1>
<ul>
<li>Structural Analysis: I really want to to gain more FEA skills</li>
<li>Thruster Design</li>
</ul>
<h1 id="skills">Skills</h1>
<ul>
<li>CAD</li>
<li>MATLAB/Python</li>
<li>FEA exposure with some ANSYS experience</li>
<li>Currently in Machining/Have Design prototyping experience</li>
</ul>
Jekyll Introduction2011-12-29T00:00:00+00:00http://vadl.github.io/lessons,jekyll/2011/12/29/jekyll-introduction
<p>This Jekyll introduction will outline specifically what Jekyll is and why you would want to use it.
Directly following the intro we’ll learn exactly <em>how</em> Jekyll does what it does.</p>
<h2 id="overview">Overview</h2>
<h3 id="what-is-jekyll">What is Jekyll?</h3>
<p>Jekyll is a parsing engine bundled as a ruby gem used to build static websites from
dynamic components such as templates, partials, liquid code, markdown, etc. Jekyll is known as “a simple, blog aware, static site generator”.</p>
<h3 id="examples">Examples</h3>
<p>This website is created with Jekyll. <a href="https://github.com/mojombo/jekyll/wiki/Sites">Other Jekyll websites</a>.</p>
<h3 id="what-does-jekyll-do">What does Jekyll Do?</h3>
<p>Jekyll is a ruby gem you install on your local system.
Once there you can call <code class="highlighter-rouge">jekyll --server</code> on a directory and provided that directory
is setup in a way jekyll expects, it will do magic stuff like parse markdown/textile files,
compute categories, tags, permalinks, and construct your pages from layout templates and partials.</p>
<p>Once parsed, Jekyll stores the result in a self-contained static <code class="highlighter-rouge">_site</code> folder.
The intention here is that you can serve all contents in this folder statically from a plain static web-server.</p>
<p>You can think of Jekyll as a normalish dynamic blog but rather than parsing content, templates, and tags
on each request, Jekyll does this once <em>beforehand</em> and caches the <em>entire website</em> in a folder for serving statically.</p>
<h3 id="jekyll-is-not-blogging-software">Jekyll is Not Blogging Software</h3>
<p><strong>Jekyll is a parsing engine.</strong></p>
<p>Jekyll does not come with any content nor does it have any templates or design elements.
This is a common source of confusion when getting started.
Jekyll does not come with anything you actually use or see on your website - you have to make it.</p>
<h3 id="why-should-i-care">Why Should I Care?</h3>
<p>Jekyll is very minimalistic and very efficient.
The most important thing to realize about Jekyll is that it creates a static representation of your website requiring only a static web-server.
Traditional dynamic blogs like Wordpress require a database and server-side code.
Heavily trafficked dynamic blogs must employ a caching layer that ultimately performs the same job Jekyll sets out to do; serve static content.</p>
<p>Therefore if you like to keep things simple and you prefer the command-line over an admin panel UI then give Jekyll a try.</p>
<p><strong>Developers like Jekyll because we can write content like we write code:</strong></p>
<ul>
<li>Ability to write content in markdown or textile in your favorite text-editor.</li>
<li>Ability to write and preview your content via localhost.</li>
<li>No internet connection required.</li>
<li>Ability to publish via git.</li>
<li>Ability to host your blog on a static web-server.</li>
<li>Ability to host freely on GitHub Pages.</li>
<li>No database required.</li>
</ul>
<h1 id="how-jekyll-works">How Jekyll Works</h1>
<p>The following is a complete but concise outline of exactly how Jekyll works.</p>
<p>Be aware that core concepts are introduced in rapid succession without code examples.
This information is not intended to specifically teach you how to do anything, rather it
is intended to give you the <em>full picture</em> relative to what is going on in Jekyll-world.</p>
<p>Learning these core concepts should help you avoid common frustrations and ultimately
help you better understand the code examples contained throughout Jekyll-Bootstrap.</p>
<h2 id="initial-setup">Initial Setup</h2>
<p>After <a href="/index.html#start-now">installing jekyll</a> you’ll need to format your website directory in a way jekyll expects.
Jekyll-bootstrap conveniently provides the base directory format.</p>
<h3 id="the-jekyll-application-base-format">The Jekyll Application Base Format</h3>
<p>Jekyll expects your website directory to be laid out like so:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>.
|-- _config.yml
|-- _includes
|-- _layouts
| |-- default.html
| |-- post.html
|-- _posts
| |-- 2011-10-25-open-source-is-good.markdown
| |-- 2011-04-26-hello-world.markdown
|-- _site
|-- index.html
|-- assets
|-- css
|-- style.css
|-- javascripts
</code></pre>
</div>
<ul>
<li>
<p><strong>_config.yml</strong>
Stores configuration data.</p>
</li>
<li>
<p><strong>_includes</strong>
This folder is for partial views.</p>
</li>
<li>
<p><strong>_layouts</strong>
This folder is for the main templates your content will be inserted into.
You can have different layouts for different pages or page sections.</p>
</li>
<li>
<p><strong>_posts</strong>
This folder contains your dynamic content/posts.
the naming format is required to be <code class="highlighter-rouge">@YEAR-MONTH-DATE-title.MARKUP@</code>.</p>
</li>
<li>
<p><strong>_site</strong>
This is where the generated site will be placed once Jekyll is done transforming it.</p>
</li>
<li>
<p><strong>assets</strong>
This folder is not part of the standard jekyll structure.
The assets folder represents <em>any generic</em> folder you happen to create in your root directory.
Directories and files not properly formatted for jekyll will be left untouched for you to serve normally.</p>
</li>
</ul>
<p>(read more: <a href="https://github.com/mojombo/jekyll/wiki/Usage">https://github.com/mojombo/jekyll/wiki/Usage</a>)</p>
<h3 id="jekyll-configuration">Jekyll Configuration</h3>
<p>Jekyll supports various configuration options that are fully outlined here:
(<a href="https://github.com/mojombo/jekyll/wiki/Configuration">https://github.com/mojombo/jekyll/wiki/Configuration</a>)</p>
<h2 id="content-in-jekyll">Content in Jekyll</h2>
<p>Content in Jekyll is either a post or a page.
These content “objects” get inserted into one or more templates to build the final output for its respective static-page.</p>
<h3 id="posts-and-pages">Posts and Pages</h3>
<p>Both posts and pages should be written in markdown, textile, or HTML and may also contain Liquid templating syntax.
Both posts and pages can have meta-data assigned on a per-page basis such as title, url path, as well as arbitrary custom meta-data.</p>
<h3 id="working-with-posts">Working With Posts</h3>
<p><strong>Creating a Post</strong>
Posts are created by properly formatting a file and placing it the <code class="highlighter-rouge">_posts</code> folder.</p>
<p><strong>Formatting</strong>
A post must have a valid filename in the form <code class="highlighter-rouge">YEAR-MONTH-DATE-title.MARKUP</code> and be placed in the <code class="highlighter-rouge">_posts</code> directory.
If the data format is invalid Jekyll will not recognize the file as a post. The date and title are automatically parsed from the filename of the post file.
Additionally, each file must have <a href="https://github.com/mojombo/jekyll/wiki/YAML-Front-Matter">YAML Front-Matter</a> prepended to its content.
YAML Front-Matter is a valid YAML syntax specifying meta-data for the given file.</p>
<p><strong>Order</strong>
Ordering is an important part of Jekyll but it is hard to specify a custom ordering strategy.
Only reverse chronological and chronological ordering is supported in Jekyll.</p>
<p>Since the date is hard-coded into the filename format, to change the order, you must change the dates in the filenames.</p>
<p><strong>Tags</strong>
Posts can have tags associated with them as part of their meta-data.
Tags may be placed on posts by providing them in the post’s YAML front matter.
You have access to the post-specific tags in the templates. These tags also get added to the sitewide collection.</p>
<p><strong>Categories</strong>
Posts may be categorized by providing one or more categories in the YAML front matter.
Categories offer more significance over tags in that they can be reflected in the URL path to the given post.
Note categories in Jekyll work in a specific way.
If you define more than one category you are defining a category hierarchy “set”.
Example:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>---
title : Hello World
categories : [lessons, beginner]
---
</code></pre>
</div>
<p>This defines the category hierarchy “lessons/beginner”. Note this is <em>one category</em> node in Jekyll.
You won’t find “lessons” and “beginner” as two separate categories unless you define them elsewhere as singular categories.</p>
<h3 id="working-with-pages">Working With Pages</h3>
<p><strong>Creating a Page</strong>
Pages are created by properly formatting a file and placing it anywhere in the root directory or subdirectories that do <em>not</em> start with an underscore.</p>
<p><strong>Formatting</strong>
In order to register as a Jekyll page the file must contain <a href="https://github.com/mojombo/jekyll/wiki/YAML-Front-Matter">YAML Front-Matter</a>.
Registering a page means 1) that Jekyll will process the page and 2) that the page object will be available in the <code class="highlighter-rouge">site.pages</code> array for inclusion into your templates.</p>
<p><strong>Categories and Tags</strong>
Pages do not compute categories nor tags so defining them will have no effect.</p>
<p><strong>Sub-Directories</strong>
If pages are defined in sub-directories, the path to the page will be reflected in the url.
Example:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>.
|-- people
|-- bob
|-- essay.html
</code></pre>
</div>
<p>This page will be available at <code class="highlighter-rouge">http://yourdomain.com/people/bob/essay.html</code></p>
<p><strong>Recommended Pages</strong></p>
<ul>
<li><strong>index.html</strong>
You will always want to define the root index.html page as this will display on your root URL.</li>
<li><strong>404.html</strong>
Create a root 404.html page and GitHub Pages will serve it as your 404 response.</li>
<li><strong>sitemap.html</strong>
Generating a sitemap is good practice for SEO.</li>
<li><strong>about.html</strong>
A nice about page is easy to do and gives the human perspective to your website.</li>
</ul>
<h2 id="templates-in-jekyll">Templates in Jekyll</h2>
<p>Templates are used to contain a page’s or post’s content.
All templates have access to a global site object variable: <code class="highlighter-rouge">site</code> as well as a page object variable: <code class="highlighter-rouge">page</code>.
The site variable holds all accessible content and metadata relative to the site.
The page variable holds accessible data for the given page or post being rendered at that point.</p>
<p><strong>Create a Template</strong>
Templates are created by properly formatting a file and placing it in the <code class="highlighter-rouge">_layouts</code> directory.</p>
<p><strong>Formatting</strong>
Templates should be coded in HTML and contain YAML Front Matter.
All templates can contain Liquid code to work with your site’s data.</p>
<p><strong>Rending Page/Post Content in a Template</strong>
There is a special variable in all templates named : <code class="highlighter-rouge">content</code>.
The <code class="highlighter-rouge">content</code> variable holds the page/post content including any sub-template content previously defined.
Render the content variable wherever you want your main content to be injected into your template:</p>
<pre><code>...
<body>
<div id="sidebar"> ... </div>
<div id="main">
{{content}}
</div>
</body>
...</code></pre>
<h3 id="sub-templates">Sub-Templates</h3>
<p>Sub-templates are exactly templates with the only difference being they
define another “root” layout/template within their YAML Front Matter.
This essentially means a template will render inside of another template.</p>
<h3 id="includes">Includes</h3>
<p>In Jekyll you can define include files by placing them in the <code class="highlighter-rouge">_includes</code> folder.
Includes are NOT templates, rather they are just code snippets that get included into templates.
In this way, you can treat the code inside includes as if it was native to the parent template.</p>
<p>Any valid template code may be used in includes.</p>
<h2 id="using-liquid-for-templating">Using Liquid for Templating</h2>
<p>Templating is perhaps the most confusing and frustrating part of Jekyll.
This is mainly due to the fact that Jekyll templates must use the Liquid Templating Language.</p>
<h3 id="what-is-liquid">What is Liquid?</h3>
<p><a href="https://github.com/Shopify/liquid">Liquid</a> is a secure templating language developed by <a href="http://shopify.com">Shopify</a>.
Liquid is designed for end-users to be able to execute logic within template files
without imposing any security risk on the hosting server.</p>
<p>Jekyll uses Liquid to generate the post content within the final page layout structure and as the primary interface for working with
your site and post/page data.</p>
<h3 id="why-do-we-have-to-use-liquid">Why Do We Have to Use Liquid?</h3>
<p>GitHub uses Jekyll to power <a href="http://pages.github.com/">GitHub Pages</a>.
GitHub cannot afford to run arbitrary code on their servers so they lock developers down via Liquid.</p>
<h3 id="liquid-is-not-programmer-friendly">Liquid is Not Programmer-Friendly.</h3>
<p>The short story is liquid is not real code and its not intended to execute real code.
The point being you can’t do jackshit in liquid that hasn’t been allowed explicitly by the implementation.
What’s more you can only access data-structures that have been explicitly passed to the template.</p>
<p>In Jekyll’s case it is not possible to alter what is passed to Liquid without hacking the gem or running custom plugins.
Both of which cannot be supported by GitHub Pages.</p>
<p>As a programmer - this is very frustrating.</p>
<p>But rather than look a gift horse in the mouth we are going to
suck it up and view it as an opportunity to work around limitations and adopt client-side solutions when possible.</p>
<p><strong>Aside</strong>
My personal stance is to not invest time trying to hack liquid. It’s really unnecessary
<em>from a programmer’s</em> perspective. That is to say if you have the ability to run custom plugins (i.e. run arbitrary ruby code)
you are better off sticking with ruby. Toward that end I’ve built <a href="http://github.com/plusjade/mustache-with-jekyll">Mustache-with-Jekyll</a></p>
<h2 id="static-assets">Static Assets</h2>
<p>Static assets are any file in the root or non-underscored subfolders that are not pages.
That is they have no valid YAML Front Matter and are thus not treated as Jekyll Pages.</p>
<p>Static assets should be used for images, css, and javascript files.</p>
<h2 id="how-jekyll-parses-files">How Jekyll Parses Files</h2>
<p>Remember Jekyll is a processing engine. There are two main types of parsing in Jekyll.</p>
<ul>
<li><strong>Content parsing.</strong>
This is done with textile or markdown.</li>
<li><strong>Template parsing.</strong>
This is done with the liquid templating language.</li>
</ul>
<p>And thus there are two main types of file formats needed for this parsing.</p>
<ul>
<li><strong>Post and Page files.</strong>
All content in Jekyll is either a post or a page so valid posts and pages are parsed with markdown or textile.</li>
<li><strong>Template files.</strong>
These files go in <code class="highlighter-rouge">_layouts</code> folder and contain your blogs <strong>templates</strong>. They should be made in HTML with the help of Liquid syntax.
Since include files are simply injected into templates they are essentially parsed as if they were native to the template.</li>
</ul>
<p><strong>Arbitrary files and folders.</strong>
Files that <em>are not</em> valid pages are treated as static content and pass through
Jekyll untouched and reside on your blog in the exact structure and format they originally existed in.</p>
<h3 id="formatting-files-for-parsing">Formatting Files for Parsing.</h3>
<p>We’ve outlined the need for valid formatting using <strong>YAML Front Matter</strong>.
Templates, posts, and pages all need to provide valid YAML Front Matter even if the Matter is empty.
This is the only way Jekyll knows you want the file processed.</p>
<p>YAML Front Matter must be prepended to the top of template/post/page files:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>---
layout: post
category : pages
tags : [how-to, jekyll]
---
... contents ...
</code></pre>
</div>
<p>Three hyphens on a new line start the Front-Matter block and three hyphens on a new line end the block.
The data inside the block must be valid YAML.</p>
<p>Configuration parameters for YAML Front-Matter is outlined here:
<a href="https://github.com/mojombo/jekyll/wiki/YAML-Front-Matter">A comprehensive explanation of YAML Front Matter</a></p>
<h4 id="defining-layouts-for-posts-and-templates-parsing">Defining Layouts for Posts and Templates Parsing.</h4>
<p>The <code class="highlighter-rouge">layout</code> parameter in the YAML Front Matter defines the template file for which the given post or template should be injected into.
If a template file specifies its own layout, it is effectively being used as a <code class="highlighter-rouge">sub-template.</code>
That is to say loading a post file into a template file that refers to another template file with work in the way you’d expect; as a nested sub-template.</p>
<h2 id="how-jekyll-generates-the-final-static-files">How Jekyll Generates the Final Static Files.</h2>
<p>Ultimately, Jekyll’s job is to generate a static representation of your website.
The following is an outline of how that’s done:</p>
<ol>
<li>
<p><strong>Jekyll collects data.</strong>
Jekyll scans the posts directory and collects all posts files as post objects. It then scans the layout assets and collects those and finally scans other directories in search of pages.</p>
</li>
<li>
<p><strong>Jekyll computes data.</strong>
Jekyll takes these objects, computes metadata (permalinks, tags, categories, titles, dates) from them and constructs one
big <code class="highlighter-rouge">site</code> object that holds all the posts, pages, layouts, and respective metadata.
At this stage your site is one big computed ruby object.</p>
</li>
<li>
<p><strong>Jekyll liquifies posts and templates.</strong>
Next jekyll loops through each post file and converts (through markdown or textile) and <strong>liquifies</strong> the post inside of its respective layout(s).
Once the post is parsed and liquified inside the the proper layout structure, the layout itself is “liquified”.
<strong>Liquification</strong> is defined as follows: Jekyll initiates a Liquid template, and passes a simpler hash representation of the ruby site object as well as a simpler
hash representation of the ruby post object. These simplified data structures are what you have access to in the templates.</p>
</li>
<li>
<p><strong>Jekyll generates output.</strong>
Finally the liquid templates are “rendered”, thereby processing any liquid syntax provided in the templates
and saving the final, static representation of the file.</p>
</li>
</ol>
<p><strong>Notes.</strong>
Because Jekyll computes the entire site in one fell swoop, each template is given access to
a global <code class="highlighter-rouge">site</code> hash that contains useful data. It is this data that you’ll iterate through and format
using the Liquid tags and filters in order to render it onto a given page.</p>
<p>Remember, in Jekyll you are an end-user. Your API has only two components:</p>
<ol>
<li>The manner in which you setup your directory.</li>
<li>The liquid syntax and variables passed into the liquid templates.</li>
</ol>
<p>All the data objects available to you in the templates via Liquid are outlined in the <strong>API Section</strong> of Jekyll-Bootstrap.
You can also read the original documentation here: <a href="https://github.com/mojombo/jekyll/wiki/Template-Data">https://github.com/mojombo/jekyll/wiki/Template-Data</a></p>
<h2 id="conclusion">Conclusion</h2>
<p>I hope this paints a clearer picture of what Jekyll is doing and why it works the way it does.
As noted, our main programming constraint is the fact that our API is limited to what is accessible via Liquid and Liquid only.</p>
<p>Jekyll-bootstrap is intended to provide helper methods and strategies aimed at making it more intuitive and easier to work with Jekyll =)</p>
<p><strong>Thank you</strong> for reading this far.</p>
<h2 id="next-steps">Next Steps</h2>
<p>Please take a look at <a href=""></a>
or jump right into <a href="">Usage</a> if you’d like.</p>