Week #1 Principals and Practices / Project management¶
What I’ve done this week¶
- Knowing about what FabLab is and sign on the agreement file and uploading it via git system.
- Thinking about my final project and drawing sketch of it.
- Leaning some project management techniques and how to do version control with git.
- Creating WEB pages using markdown.
Weekly Assignment Requirement¶
- Plan and sketch a potential final Project
- Complete a Git Tutorial
- build a personal site in the class archive describing you and your final project
Description of Assignment Work.¶
final project sketch¶
This week I worked on defining my final project idea and started to getting used to the documentation process.
project name:
Off-grid I/O module controller
what it will do
my product will be used in outdoor situation for sensing data like human-sensing, temperature, humidity and execute program like lighting, taking a photo and so on. simply speaking, it will be outdoor arduino(or esp32). and it will work without power supply from outside because it has solar system to generate own power. and also it will connect with network so
users can control it from remote situation.
who will use it
it will be super-user-friendly for the people not to be familiar with programing and electronics. it aims that all the people can use microcomputer outside without thinking complicated stuff.
my first idea
My hometown has lots of farm roads along fields. It is useful cause it could be shortcut rather than taking a wide national route. But in the evening, the road seems really dangerous to go through especially you are not accustomed to it because there are no light.
So firstly, I planned to create off the grid light poles to put them along the farm roads. It must be great help that people walk through safely in the nighttime. And also preventing from light pollution, it emits light only when people pass it through in front. I was thinking to use LEDs and a PIR motion sensor and also add BLE connection for remote controlling and solar battery unit for self-power supply per one pole. If the system build successfully, It would look like a light follows a person who walks through the farm road in the dark.
developed a little…
In my first plan, fixed input and output parts were two in total. If I design these two parts as changeable modules, I can treat the pole not only lighting stuff but also data collecting tool. It might be utilized in agricultural usage.
So now, my IDEA has been slightly changed from the first one. I am thinking to create an off-grid I/O module controller whose shape is like a pile. It means that my outcome is going to be the micro controller and I/O modules specialized in outdoor use.
The device consists of four parts. The top part includes solar battery unit, micro controller, and BLE transmitter. The second and third parts are the module part. Users can choose modules like LED, speaker, various sensors etc. and set the function of it easily each time. And the last part is a pile part for driving the end of the device into soil.
Each part is connected by screw joint and keep the electrical connection by conductive plates (maybe engraved copper one) which are attached bottom and edge of screws. Modules are ready-to-connect so users do not need to think of electrical connection complicatedly. They just need to screw and connect them.
project management¶
- Hierarchical and Modular Planning
- Triage
- Supply-Side Time Management
- Parallel Development
- Spiral Development
- Bottom-up Debugging
- documentation skill
- As-You-Work Documentation
- notebook
- data
- photo
- video
- important rule →10MB per week About. 200kb-500kb each is good Total 500mb I can use
-
image file size control
- Xncoverter
- batch control on photoshop
decided to install Xnconverter for image files editing
- As-You-Work Documentation
version control with git¶
to upload own website on GitLab, I need to use git.
git is a version control system which creates historical records of file changes and especially effective for collaborative works.
repository (hereinafter referred to as repo) = file storage
use terminal (CLI stands for command line interface)
which let us control a computer by commands instead of visual based user interface (GUI stands for Graphical User Interface) like clickable icons.
basically, there are two repos which I use. one is on GitLab and the other is on my laptop. and make a SSH connection to manage files between two repos.
SSH is a encrypted connecting system. it uses two keys between server and laptop to start connecting. One is public key which should be stored in both server and laptop, another one is called private key which exists only laptop side.
When connecting is started, server side generates an encryption with public key and gives it to laptop side. laptop side restores it and give back to server side. then the connection between them are permitted.
Our instructor Rico explained the git system to us with this diagram
What I need to do for start using git are…
- install git
- SSH key preparation
- make repo for laptop side
preparation for using git¶
preparing git environment with terminal
1. install homebrew
homebrew is package management tool to manage softwares and libraries easily. I will download softwares a lot while taking FabAcademy so install this at first.
entered the command suggested on official site
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
finished downloading easily
2. install git
install git using homebrew
$ brew install git
installed successfully!
then, tried git config setting using cheat sheet by FabAcademy
git config —global user.name “your_name”
git config —global user..email “your_mail@mail.com”
3. create SSH key
ssh-keygen -t rsa -C "$your_email"
show ssh key on terminal window
cat ~/.ssh/id_rsa.pub
”~” means “home” directory
copy public key
pbcopy < ~/.ssh/id_rsa.pub
and paste it to gitlab to activate ssh connection on
https://gitlab.fabcloud.org/profile/keys
done! now I got the connection between GitLab and my laptop!!
4. clone repository
clone means copy in the git world. so make a copy of the repo from remote environment (online) to local environment (my computer).
before cloning, set directory where I want to create repository
I can change directory to use cd command. and (/) means root which mean first directory in the computer.
$ cd /
decided to create directory for repo on root directory. I can do it from terminal as well to use make directory command here.
$ mkdir name (this time I set as "fabacademy_repo")
and use ls command which I can check components inside directory
$ ls
directory “fabacademy_repo” has been created on root directory successfully!
so I move into fabacademy_repo.
and finally, clone command
$ git clone
logs showed up and finished!
at last line, I checked the existence of cloned directory by ls command.
here is a file tree of local repo.
Trying to edit agreement file as a practice¶
move to directory agreement file exist. then edit it to use nano command. nano is text editor we can use from terminal.
$ cd yuki-oka/docs/about
$ nano agreement.md
after saving the edited file, upload it via git.
here is a history
git add
↓
git status *optional
↓
git commit
↓
git push
is a series of action to upload files.
I will upload my webpages in this way from now on!
also tried git pull with online edited agreement file.
when save a file online, commit was done automatically so I could only need to pull from remote to local.
finally, I learned git’s basic use!
[TIPs]frequent use git commands
$ git pull
get latest version file from remote repo
$ git add .
or
$ git add filename
put files staging status. (.) means all. the difference is put all the file or a specific file
$ git status
checking status wether any files committed or not
$ git commit -m “any comment”
saving changes on repo with a comment
$ git push
uploading changes from local to remote
ctrl + c
(Linux command) ending the running program
[TIPs]how to stop if asked password everytime push/pull
every time I was asked password when I pull/push I found the solution to use keychain to stop it.
edit ./.ssh/config file →but I didn’t have it in .ssh folder so need to create config file
$ touch config
touch command creates file
and write down setting sentences below on it.
Host *
UseKeychain yes
AddKeysToAgent yes
After this type password once, I haven’t been asked password when I push and pull anymore!
[TIPs]useful shell commands I found
$ history
can check commands which I inputted
$ script filename.log
(to finish)
ctrl + d
can keep all the logs indicated on my terminal display while this command running
making my website with markdown¶
what is markdown?
markdown is a kind of markup language, created for writing code easily and possible to convert HTML.
.gitlab-ci.yml file build all .md files included by docs folder as HTML files following the setting in mkdocs.yml file.
how to write markdown is really simple and the appearance of the outcome is sophisticated as well.
here is code list I used this time.
# A
## A
### A
#### A
set font size and hierarchical index
don’t space space before the word!
image
link
<br>
new line
-
or
+
or
*
middle black
don’t space space before the word!
1.
2.
3.
decimal list
need blank line front and back of the number + period! bind by \
tag!!
>
quote
\```
\```
backtick
thick background color. not need backslash when you write actually.
looking for a good text editor¶
for writing markup language, I decided to find good text editor. I checked some this time. but it is really short term of using. so I will keep up exploring editors to find the best one for me while taking FabAcademy.
vim
vim is designed for CLI/CUI. complicated for me cause it need original operation like using I key to start editing file.
but once I feel comfortable when I want to edit files from terminal directly like create config file. this could be good editor if I get used to CUI but not now.
nano
similar to vim in terms of usability from terminal but may be easier than that because of its command but still hard to use for beginners like me.
atom
easy to use, I personally used this editor so I don’t have any complaint to this. though this first time using for markdown, I could find suitable library for editing markdown quickly like sprit window preview. even spellchecking library exists. being able to check file tree on the left column is nice as well.
used library : Markdown preview
brackets
this app has live preview mode. it sets up local server on browser by itself. But need to add library to check markdown file on that mode.
visual studio code
super easy to use it with markdown because already has preview system with shortcut key command+k→v. split display to show preview quickly awesome! but image file not shown on preview. I heard many developers contributing for this app at the moment and lots of mentors in FabLab Kamakura use this editor so I will try this for a while.
useful extensions
- Spell Right
multilingual spellchecker. this tells us typos by red wavy underline. you can activate this extension to set
"spellright.language": [ "en" ]
on the setting.json or put the code below on the editing file.
%% spellcheck-language "en"
using MkDocs on my local computer¶
mkdocs is one of the package for python called static site generator which generate html files from markdown files.
it provides us easy creating web page experience.
for normal using GitLab, I don’t need to use Mkdocs on local environment because it only runs on remote server. but if I want to make the same develop environment as remote repo on my local for test uploading. I have to install mkdocs to run it when I set up local server.
mkdocs is a library for python. so I should install python before getting mkdocs.
python has 2 versions, old one is called normal python and new one is python3. I heard gradually finish supporting for old python so I tried install python3 this time.
1. install python3
$ brew install python3
(just for testing) activate python3
$ python3
you can run program inline like below.
>>> 1 + 1
2
exit python3
Ctrl + D
or
>>> exit()
2.install mkdocs via pip3
pip3 is installed automatically when installed python3.
it is package control software for python3. be careful to use
version of pip because you have to match version of both pip and python.
$pip3 install mkdocs
version check
$ mkdocs --version
now installed successfully, then activate local server. move to local repo (directory one level higher than docs)
$ cd /fabacademy_repo/yuki-oka
after changing directory, time for run server
$ mkdocs serve
activate local server with the files and directories under present working directory
Fail!
Cause racking material error so install it
$ pip3 install mkdocs-material
try again
$ mkdocs serve
Working!
web site generated by mkdocs is shown on Local server http://127.0.0.1:8000
If I edit the markdown file, the site would be changed as I edited simultaneously.
For this I made 3 markdown files, About, Assignment/week01, Final Project successfully.
TIPs etc.¶
to see hidden files and folders (name start from (.) usually don’t show up do we need command to see them)
shift + command(⌘) + dot(.)
Description of Important Weekly Learning Outcome¶
Project management skill is apparently important notion for FabAcademy’s work because we have to finish a massive amount of experiments and assignments every single week. Instructors gave me some techniques for accomplishing it. Though they seem to be needed different procedures, I think what important in common for all the technique is to understand what my project is precisely. Then I must be able to divide the whole project into tasks and make a schedule of the week, and so on. I want to acquire the skill to grasp the present project with precision as soon as possible. And also, documentation skill is important to show what I have done throughout the FabAcademy period. So, I would like to get used to its skills like note taking, taking photos and movie all the time, creating webpage with markdown, using git to control uploading files.
Links to Files and Code.¶
Appendix.¶
What is SSH? (Japanese source)
For macOS, solution for every time being asked password on git(Japanese source)