petRockBlog http://blog.petrockblock.com Fun stuff for technics enthusiasts Sun, 26 Feb 2017 20:34:57 +0000 en-US hourly 1 https://wordpress.org/?v=4.7.2 Update for the ControlBlock Driver http://blog.petrockblock.com/2017/02/19/update-for-the-controlblock-driver/ http://blog.petrockblock.com/2017/02/19/update-for-the-controlblock-driver/#comments Sun, 19 Feb 2017 15:02:19 +0000 http://blog.petrockblock.com/?p=123028 ControlBlock Update

The driver of the ControlBlock got updated! What does this mean for you? More functionalities!

More specifically, the updates contain:

  1. 4-player support
    Multiple ControlBlocks can be stacked on top of each other. With this functionality you can now create your 4-player arcade machine with two ControlBlocks. Each ControlBlock can be configured with its own controller type. That means for example that you could provide two full sets of arcade controllers and two, say, SNES controllers – you can choose!

  2. Genesis/Megadrive controller support
    The driver now support Genesis / Megadrive controllers. Both types, the three as well as the six button controllers, are supported. To use Genesis controllers with the ControlBlock simply set “genesis” as gamepad type in the driver config file.
    Sega Genesis / Megadrive (TM) Controllers are now supported by the ControlBlock

  3. Custom shutdown script
    We got several requests from users who want to execute their own scripts when the power switch is switched to “off”. The whole shutdown actions are now defined in the file /etc/controlblockswitchoff.sh You can add anything you want to be executed on switch off to that script now.

  4. Reset button for SNES gamepad mode
    SNES mode now also provides a reset button functionality. If you want to build your personal retro-gaming machine within a SNES or NES case you can now also connect the reset button to the ControlBlock. The reset button is mapped to the ESC key, which in turn exits for example a running emulator.
    ControlBlock Connected with Nintendo SNES (TM) Reset Button

All configuration settings and detailed information about the other functions are described at the Github site of the driver.

Besides updates of the ControlBlock driver there are now driver modules for the ControlBlock (and the PowerBlock as well) in RetroPie. That makes it even easier for you to install the PowerBlock or ControlBlock driver for your RetroPie project. You find the drivers in the RetroPie-Setup menu at “Manage packages” –> “Manage driver packages” –> “controlblock”. From there, you can easily install or remove the driver from within the RetroPie Setup.

We hope you enjoy these new features!

If you are missing any functionality or support for different controllers feel free to comment below.

]]>
http://blog.petrockblock.com/2017/02/19/update-for-the-controlblock-driver/feed/ 1
New Revision of the PowerBlock: Increased Flexibility http://blog.petrockblock.com/2016/05/20/new-revision-of-the-powerblock-increased-flexibility/ http://blog.petrockblock.com/2016/05/20/new-revision-of-the-powerblock-increased-flexibility/#comments Fri, 20 May 2016 20:15:15 +0000 http://blog.petrockblock.com/?p=122629 The PowerBlock is a small support shield for the Raspberry Pi that provides a power switch functionality. Recently, we have updated the design of the PowerBlock such that it now offers an even greater flexibility regarding the connections with the Raspberry Pi.

Here is an image of the new PowerBlock Revision 1.1:

IMG_2907

Besides some fine tunings in the board layout, these are the major differences to the previous revision of the PowerBlock:

Additional signal breakouts so that input voltage, output voltage, and control signals
All the signal above can now be attached to the Raspberry Pi without using the 2×6 pin connector. As you can see on the image below, there are individual pin outs for the 5V input voltage, the 5V output voltage, as well as for the control signals S1, and S2.

IMG_2907_zoom

The pin out is as following:

5V IN, +,-: supply voltage
S1: pin 12
S2: pin 11
5V OUT +: pin 2 or pin 4
5V OUT -: pin 6 or pin 9

Additional mounting hole for attaching a Raspberry Pi Zero
This addition makes it possible to not only mount the PowerBlock to the Raspberry Pi model A and B, but also to the Raspberry Pi Zero. Here are some exemplary images for the various models:

RPi Model A RPi Model B RPi Zero
IMG_2912  IMG_2911  IMG_2909 

Together with a toggle switch the PowerBlock provides a reliable and safe power switch functionality for the Raspberry Pi. An optional LED can also be attached to the PowerBlock that serves as a power status indicator.

IMG_2913

You can find more details and a comprehensive installation and configuration description on the description site of the PowerBlock.

]]>
http://blog.petrockblock.com/2016/05/20/new-revision-of-the-powerblock-increased-flexibility/feed/ 37
Python module for MCP23S17 for use with the Raspberry Pi http://blog.petrockblock.com/2016/05/15/python-module-for-mcp23s17-for-use-with-the-raspberry-pi/ http://blog.petrockblock.com/2016/05/15/python-module-for-mcp23s17-for-use-with-the-raspberry-pi/#comments Sun, 15 May 2016 13:50:14 +0000 http://blog.petrockblock.com/?p=112746 IMG_2906_FotorSome time ago I revised the hardware design of the ControlBlock and added test points for all major signals. The overall aim was to build a device for doing final system tests that are done before any single ControlBlock leaves for shipping. These system tests are written in Python. This post is about a Python module for the MCP23S17 to be used on a Raspbbery Pi.

Basically, the tests set various input signal lines to logical high and low values in a specific order and test if certain output signals have the correct level. To do this, another manually tested ControlBlock is used. Since revision 2.X the ControlBlock uses MCP23S17 GPIO expanders to provide 32 input/output lines for arbitrary usage. I did not find any Python abstraction that would allow me to easily access the MCP23S17 from a Raspberry Pi, so I decided to write a Python module myself.

The result is a publicly available Python module, available via PyPI, that you can install with pip.

Installing the Module

If not already done, you need to install PIP via::

sudo apt-get install python-dev python-pip

Then you can install the module from PyPI via

pip install RPiMCP23S17

That’s it!

Interface of the Module

So, how do you use the module. How does its interface look like? Here is a list of the public methods of the module together with brief descriptions:

  • Constructor – Initializes an instance given the SPI bus number, the chip-enable (CE) number, and the device ID of the MCP23S17 component.
  • open – Opens the configured SPI-bus with hardware-address access and sequential operations mode.
  • close – Closes the SPI connection that the MCP23S17 component is using.
  • setPullupMode – Enables or disables the pull-up mode for a given input pin.
  • setDirection – Sets the direction for a given pin.
  • digitalRead – Reads the level of a given pin.
  • digitalWrite – Sets the level of a given pin.
  • writeGPIO – Sets the 16-bit data port value for all pins.
  • readGPIO – Reads the 16-bit data port value of all pins.

You can find a detailed documentation in the Python docstrings of the module.

Exemplary Usage

Here is some demo code that also comes with the module sources. The demo periodically toggles all pins of two MCP23S17 expanders:

mcp1 = MCP23S17(deviceID=0x00)
mcp2 = MCP23S17(deviceID=0x01)
mcp1.open()
mcp2.open()

for x in range(0, 16):
    mcp1.setDirection(x, mcp1.DIR_OUTPUT)
    mcp2.setDirection(x, mcp1.DIR_OUTPUT)

while (True):
    for x in range(0, 16):
        mcp1.digitalWrite(x, MCP23S17.LEVEL_HIGH)
        mcp2.digitalWrite(x, MCP23S17.LEVEL_HIGH)
        time.sleep(1)

    for x in range(0, 16):
        mcp1.digitalWrite(x, MCP23S17.LEVEL_LOW)
        mcp2.digitalWrite(x, MCP23S17.LEVEL_LOW)
        time.sleep(1)

So, if you are tinkering with MCP23S17 components and Python on a Raspberry Pi, you might find this module to be helpful for you.

You can find the module on PyPi here.

By the way, here is an image of the testing station for the ControlBlocks, which we are using to do the final system tests before shipping:

IMG_2905
System Test Station for the ControlBlock using the MCP23S17 and test scripts written in Python
]]>
http://blog.petrockblock.com/2016/05/15/python-module-for-mcp23s17-for-use-with-the-raspberry-pi/feed/ 2
RetroPie 3.6 is Released http://blog.petrockblock.com/2016/03/02/retropie-3-6-is-released/ http://blog.petrockblock.com/2016/03/02/retropie-3-6-is-released/#comments Wed, 02 Mar 2016 06:29:40 +0000 http://blog.petrockblock.com/?p=118794 Pixel-ArtRetroPie on Raspberry Pi 3? Get RetroPie 3.6!

This version is released a little earlier than originally planned, due to the release of the fantastic Raspberry Pi 3 – which our previous 3.5 will not boot on due to having out of date firmware. Along with Raspberry Pi 3 compatibility this release brings a bunch of interesting experimental emulators such as Daphne for emulation of classic LaserDisc arcade games, a myriad of libretro cores, and a few game engines. We’ve also worked around the pesky insert coin bug that has plagued the arcade emulators.

You can find the links for the SD-card images as usual in the Downloads Sections.
Installation Instructions can be found at Github: https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation

Changes since 3.5:

Added Support for the Raspberry Pi 3

  • Added new experimental modules:
    • Daphne (Laserdisc Emulator)
    • Libretro-QuickNES
    • Libretro-Beetle PSX (x86 only)
    • Libretro-Beetle Lynx
    • GemRB engine (Baldur’s Gate, Icewind Dale, Planescape)
    • ResidualVM (Engine for Grim Fandango and Escape from Monkey Island)
    • Libretro-MESS (based on the most recent version of MAME)
    • Libretro-MAME (based on the most recent version of MAME)
  • Added EmulationStation theme Simpler Turtle Pi to the theme installer from Omnija.
  • Added version details and uninstall option to the RetroPie Setup Script.
  • Fixed insert coin not working on arcade based emulators.
  • Various other bugfixes and improvements.
]]>
http://blog.petrockblock.com/2016/03/02/retropie-3-6-is-released/feed/ 47
RetroPie 3.5 is Released http://blog.petrockblock.com/2016/02/06/retropie-3-5-is-released/ http://blog.petrockblock.com/2016/02/06/retropie-3-5-is-released/#comments Sat, 06 Feb 2016 16:00:30 +0000 http://blog.petrockblock.com/?p=116351 Pixel-ArtWe are pleased to announce the release of RetroPie 3.5.

After taking into consideration the feedback from the vibrant RetroPie community, we have provided a few more functions to simplify the user experience such as automatic expansion of the filesystem on boot, less terminal text, and more configuration options for the runcommand launch menu. We have also fixed up some bugs with Raspbian Jessie such as the USB ROM service and have added two new experimental modules – the Löve game engine and a ColecoVision emulator (CoolCV).

You can find the links for the SD-card images as usual in the Downloads Sections.
Installation Instructions can be found at Github: https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation

Changes since 3.4:

  • Added new experimental modules, Lӧve 2D Game Engine, Colecovision (CoolCV).
  • Debian usbmount package fixed up for systemd udev compatibility, making the USB ROM service work properly again without being killed after 30 seconds. Also added ntfs support by default.
  • Added an arcade rom folder option where all arcade games can be placed.
  • Improvements to EmulationStation (Fix crash on rom delete, direct launch, symlink support, and other bug fixes).
  • Improvements to the Runcommand Launch Menu: Cleaner dialog on launch, ability to show game artwork on launch, ability to disable joystick support as well as the ability to disable the entire runcommand launch menu.
  • PS3 Controller improvements – Add multiple gasia and shanwan controller support.
  • Updated lr-mgba emulator binaries (new upstream release of mgba 0.4.0)
  • Improvements on pre-built image – disabled screen blanking, quieter boot, and filesystem automatically expanded on first boot.
  • Various other bug fixes.
]]>
http://blog.petrockblock.com/2016/02/06/retropie-3-5-is-released/feed/ 25
RetroPie 3.4 is Released http://blog.petrockblock.com/2016/01/21/retropie-3-4-is-released/ http://blog.petrockblock.com/2016/01/21/retropie-3-4-is-released/#comments Thu, 21 Jan 2016 20:36:25 +0000 http://blog.petrockblock.com/?p=114675 Mostly fixes and improvements rather than new stuff this time folks.

There were some problems with our RetroArch configuration defaults in RetroPie 3.3 which should be sorted now, and we have fixed up a few things that didn’t work correctly with Raspbian Jessie. We also have added early support for using the RetroPie-Setup script on a X86/X11 desktop setup, as well as some basic support for building EmulationStation & RetroArch + cores on the ODroid-C1. For more information regarding installation on x86 see https://github.com/RetroPie/RetroPie-Setup/wiki/RetroPie-Ubuntu-15.10-x86-Flavor.

We are now using Raspbian Jessie as the base for the RetroPie image. Those using Wheezy can update RetroPie-Setup and emulators by following the instructions at https://github.com/RetroPie/RetroPie-setup/wiki/Updating-RetroPie – however moving to Jessie is recommended. As it takes time to pre-build binaries, in the future we will only be providing pre-built binaries for Raspbian Jessie.

You can find the links for the SD-card images as usual in the Downloads Sections.
Installation Instructions can be found at Github: https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation

Changes since 3.3

  • Now using Raspbian Jessie for the RetroPie image.
  • Fixes for controller input issues with RetroArch including improved config generation to work around problems with 8bitdo controllers.
  • Fixed up Bluetooth pairing module on Jessie.
  • Improvements to the Xbox userspace driver (xboxdrv) including partial support of Xbox One controller.
  • Can now choose to exit or restart Emulation Station. Metadata will no longer be lost if choosing to shutdown or reboot.
  • Preliminary support for using the RetroPie-Setup script on x86 + X11 on Debian/Ubuntu and Ubuntu on the Odroid-C1 (building from source only).
  • $HOME/.emulationstation has relocated to /opt/retropie/configs/all/emulationstation – but is symlinked from the original location. The USB Rom Service script will backup all of /opt/retropie/configs to USB. Previously it only backed up /$HOME/.emulationstation.
  • Support for choosing RetroArch shaders and overlays from the RetroPie-Setup configuration editor.
  • Added pixel theme from Rookervik to theme installer.
  • Wonderswan and NeoGeo Pocket separated into Wonderswan/Wonderswan Colour, NeoGeo Pocket/NeoGeo Pocket Colour.
  • Various other bugfixes and improvements.
]]>
http://blog.petrockblock.com/2016/01/21/retropie-3-4-is-released/feed/ 3
MEAN adventures continued: An UML Online Editor for PlantUML http://blog.petrockblock.com/2015/12/23/mean-adventures-continued-an-uml-online-editor-for-plantuml/ http://blog.petrockblock.com/2015/12/23/mean-adventures-continued-an-uml-online-editor-for-plantuml/#respond Wed, 23 Dec 2015 09:56:06 +0000 http://blog.petrockblock.com/?p=112297 Some weeks ago I wrote about my recent journeys into the world of web application development and the MEAN stack. While writing that blog post I realized that I would like to insert a certain UML diagram. So I first started to draw an UML diagram for a better explanation of the use cases that my learning project should implement. I did that with a tool that was locally installed on my machine and things did not work out as fast as I expected. I started to think about an alternative … the resulting UML editor and sharing platform can be found at texwriting.com.

Motivation

I realized that I did not really want to install a specific UML editor on my machine or spend too much time to look for another UML service. Instead, I would like to use an online UML editor that would let me edit, manage, and share the UML diagrams for my articles. Of course, there already exist other online UML editors, but I did not exactly find what I was looking for and I also liked the idea to implement something like that myself — what a great opportunity to continue my experiments with the MEAN stack and, specifically, getting to know user management concepts with Angular.js and Node.js! So, I decided to create the UML editor as an addition to the tool site texwriting.com that I wrote about some weeks ago.

So, here it is: An online UML editor based on PlantUML. What is PlantUML? PlantUML is an application-specific language for describing UML diagrams. It allows you to create UML diagrams just by describing it in text form. It is well-formed and human-readable. I like the idea of a textual UML diagram representation, because it the user to describe exactly those elements and only those elements that are important and the user does not have to care for the layout or arrangement of the elements in the first place.

Functionalities

So, what does the UML editor do? The following figure gives an overview about the use cases of the editor. It is actually a use-case diagram that was created and is hosted with the presented UML editor:

The platform offers the functionalities

  • (of course) to edit UML diagrams with the help of PlantUML syntax,
  • to generate the diagram images in various file formats,
  • to embed and share diagrams with other users or websites,
  • to load PlantUML templates for different types of UML diagrams.

Further more, I have added functionalities for managing user accounts and documents that can be associated to individual users.

A more detailed (and slightly overloaded) version of the overview about the use-cases is given in the following diagram. That diagram was the used for guiding the work on this editor:

Use cases, more detailed

The editing view is split into two parts: The left side contains the editor, and diagram configurations. The right part shows the actual diagram:

Editing view

One feature that turned out to be very helpful is an auto-update function: If the textual diagram description has changed the diagram preview is updated automatically. This allows for a seamless work flow when editing a diagram.

In order to use the document management functions, you need to sign up a free user account,

User profile view

The document management functions are located within a sidebar,

UML document management in the sidebar

Also, the platform at is intended to be used for hosting the diagram image files. This makes sharing and embedding the diagrams into other websites easy. The diagrams that are shown in this article are already created and hosted with texwriting.com. In order to embed a diagram you simply copy the link of the image format of your choice,

The sharing view

and insert the URL into your website, for example, via an image HTML tag

<img src="https://www.texwriting.com/api/v1/uml/get/svg/4b54492ca2b328ae739a58235712955c" alt="An exemplary diagram" />;

or via Markdown as

![An exemplary diagram](https://www.texwriting.com/api/v1/uml/get/svg/4b54492ca2b328ae739a58235712955c)

Behind the Curtains: Some of the used Javascript Libraries

For those of you that are interested in some technical details, here are some Javascript libraries that I used for the implementation of the functionalities:

angular-toastr

An Angular.js library for non-blocking visual notifications or toasts. It has a simple API, for example:

app.controller('foo', function($scope, toastr) {
    toastr.success('Hello world!', 'Toastr fun!');
});

yields this notification toast:

jwt-simple

This library provides functions for handling JSON web tokes. A well-written tutorial about it can be found here. JWTs are used for user authentication on the server-side of texwriting.com. Some exemplary code for generating a JSON Web Token might look like this:

function createJWT(user) {
    var payload = {
        sub: user._id,
        iat: moment().unix(),
        exp: moment().add(14, 'days').unix()
    };
    return jwt.encode(payload, config.TOKEN_SECRET);
}

moment

The library moment.js provides functions for parsing, validating, manipulating, and displaying dates in Javascript. An exemplary date manipulation looks like this:

var today = moment().startOf('day')
var aMonthAgo = moment(today).subtract(30, 'days')

winston

The Winston library is designed to be a simple and universal logging library for Node.js. IT allows the configuration of multiple storage devices for the logs, for example, the console, files, or a database.

Gulp

Gulp is not a Node.js library for direct inclusion into your application, but a task automation framework. I use it for linting the Javascript files, as well as for minifying the Javascript and HTML files.

Summary and Conclusions

In this project I implemented an online UML editor platform that allows to edit, collaborate and share UML diagrams. The platform makes use of PlantUML. This small project taught me how to do user management with Angular.js and Node.js. The UML service is available at texwriting.com. Looking back, I realize how easy it was to add the PlantUML compiler to the Node.js server. Having implemented all the mentioned functionalities I can say that I enjoy creating and embedding diagrams with that platform now. I have ideas for optimization here and there, but the site is already working quite well.

]]>
http://blog.petrockblock.com/2015/12/23/mean-adventures-continued-an-uml-online-editor-for-plantuml/feed/ 0
RetroPie 3.3 Released http://blog.petrockblock.com/2015/12/22/retropie-3-3-released/ http://blog.petrockblock.com/2015/12/22/retropie-3-3-released/#comments Tue, 22 Dec 2015 10:42:51 +0000 http://blog.petrockblock.com/?p=112242 After rolling new images, fixing bugs, re-rolling we are finally there: RetroPie 3.3.

Major features of this release include

  • Mupen64plus and Reicast controller configuration added to the EmulationStataion controller config setup.
  • Playstation Portable emulator ppsspp included by default now.
  • New exprimental module for OpenTTD
  • Jessie images as BETA releases.

And many smaller bug fixes and improvements. You can see details in the change log below. The Jessie images are to be considered BETA as there may be bugs in configuration modules or emulators that are not present on the Wheezy version.

We plan to move to Jessie only with the next release so that we can concentrate on maintaining only four instead of eight images. Everyone is invited to give feedback if you experience problems with your RetroPie Jessie setup.

Thanks to everyone who has contributed to this release!

You can find the SD-card images in the Downloads Sections.
Installation Instructions can be found at Github: https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation

Change Log RetroPie 3.3

  • Mupen64plus controller configs (including hotkeys) and Reicast (Dreamcast) controller configs added to the autoconfiguration script in emulationstation. Mupen64plus is now the default n64 emulator due to compatibility.
  • AdvanceMAME 1.4 (replaces 1.2 – still based on MAME 0.106).
  • PlayStation Portable emulator ppsspp is included by default (libretro version is default, the standalone version is optional).
  • Removed cpc4rpi emulator, and added CapriceRPI which has many improvements over cpc4rpi.
  • Updated libretro binaries including lr-fba-next updated to v0.2.97.37, and an improved lr-caprice32 which is now moved out of experimental and is the default Amstrad CPC emulator.
  • Updates to Reicast emulator, which has been moved out of experimental.
  • New experimental modules: OpenTTD (open source simulation game based on Transport Tycoon Deluxe), Wolf4SDL (Port of Wolfenstein 3d), Zdoom (Enhanced Port of the official DOOM source)
  • PS3 controller improvements (added Gasia PS3 clone Support).
  • Updated OpenMSX emulator (to the dev version 0.12.0+).
  • Beta images based on Raspbian Jessie are included. They may have bugs that are not present in the Raspbian Wheezy release.
  • New themes added to the theme installer (Eudora from AmadhiX, Tronkyfran from Tronkyfran, and Retroplay Canela from InsecureSpike).
  • RetroArch joy-config tool removed (custom configs are now done through the RGUI or manually).
  • Various other bugfixes/improvements.
]]>
http://blog.petrockblock.com/2015/12/22/retropie-3-3-released/feed/ 22
Supply Status of the ControlBlock http://blog.petrockblock.com/2015/12/14/supply-status-of-the-controlblock/ http://blog.petrockblock.com/2015/12/14/supply-status-of-the-controlblock/#comments Mon, 14 Dec 2015 07:06:34 +0000 http://blog.petrockblock.com/?p=111778 This info post is interesting for you, if you were looking at the ControlBlock and wondering when it will be available again.

UPDATE 01/23/2016: A new batch of ControlBlock has arrived and is now available.
UPDATE 01/23/2016: All pre-ordered ControlBlock are shipped.
UPDATE 01/13/2016: Reworking the ControlBlock is in progress. Every unit that successfully went through rework and quality check is shipped a day later.

These are information from 12/14/2015. The production of a new batch of ControlBlocks was ordered about two months ago and they were expected to be delivered at the beginning of December. In the meantime the ControlBlocks arrived (good), but we realized that one of the components was not the correct one (bad). The wrong component affects the core functionality of the ControlBlock – to attach controllers – and makes it unusable. I do not want to repeat the words that followed right after finding that out here, but I was not amused to say the least. So, what now?

First of all, a new batch with the corrected component is already ordered. When that order arrives the supply of ControlBlocks will not be short anymore. Also, luckily, the existing ControlBlocks with the wrong component can be reworked – the wrong component can be replaced with the correct one. However, that takes some time and we still have to evaluate how long exactly it takes to do that. It is planned that as soon as a bunch of ControlBlocks is reworked they will be made available in the store. Would you be interested in a pre-order functionality? In that way, the orders could be fulfilled chronologically and we would know the exact demand … Please use the comments section below to give feedback about that idea. UPDATE 12/16/2015: We have added a pre-order option for the ControlBlock now.

Did I already mention that the new ControlBlock comes fully assembled, use the SPI interface (which is way faster than the previously used I2C interface), comes with a stackable pin header, and provides additional minor tweaks in its circuitry.

IMG_2807_1024

I am sorry for everyone who is waiting and looking forward to finish their project. I hope that this info post gives you some insights into the current status of the ControlBlock supply.

]]>
http://blog.petrockblock.com/2015/12/14/supply-status-of-the-controlblock/feed/ 21
Getting to know the MEAN stack with a LaTex Web Application http://blog.petrockblock.com/2015/12/05/getting-to-know-the-mean-stack-with-a-latex-web-application/ http://blog.petrockblock.com/2015/12/05/getting-to-know-the-mean-stack-with-a-latex-web-application/#comments Sat, 05 Dec 2015 18:19:47 +0000 http://blog.petrockblock.com/?p=110416 Some time ago I had the idea for a web application related to another popular project. I quickly realized that my knowledge about web application architectures and designs was quite archaic. To learn the basics of modern web application programming I decided to implement an online assistant for writing letters based on the word-processor LaTex. It can be found at www.texwriting.com. This article gives an overview about this application and provides the essential resources that I used during the development.

TL;DR

I got to know the MEAN stack, an open-source JavaScript software stack for developing web applications. The web application provides an assistant for creating nicely typed letters based on the typesetting system LaTex. You can find the web application at www.texwriting.com. This article provides information about the motivation, details to the used components, and links to resources that came in handy during the development.

Introduction

Some time ago I had the idea for a web application with some user interactivity, some database interaction, responsive user-interface, and server-side computations. When I finally took my time and started to work on that I quickly realized that my old-school knowledge about HTML, some CSS, PHP and MySQL were light-years behind current web application concepts and standards. I decided to take my time and dig deeper into this and to create a website that offers an assistant for writing letters, which makes use of the typesetting system LaTex to generate nicely typed PDFs.

After a lot of reading, try-and-error, and concentrated coding the letter application that can be found at www.texwriting.com got all the functionality that I had in mind in the end. This article gives an overview about the application itself as well as about the resources that I used during the work on it.

A Web Application for Writing Letters Based on LaTex

So, what is the web application supposed to do? I wanted to implement something that would make use of concepts that I would also need in other web application. Here is a list of use cases of our UML assistant:

Well, quite some things to do:

  • The user should be able to edit the content of the different letter areas. Only form fields should be filled and the user should not be confronted with any LaTex-specific syntax.
  • The user should be able to generate a document out of the provided letter content. Generating the document out of the letter information should be very simple, in the best case the document should be generated automatically. All data that is sent to and received from the server should be encrypted. The user should have a possibility to save the data on his local machine. Also, the number of generated documents should be counted in a database.
  • The user should be able to save the letter as PDF as well as JSON object.
  • The user should be able to load the information of a letter into the application. In this way the user is able to re-use previously written letter data.
  • The user should be able to provide feedback. The feedback should be displayed on the website and provide discussion threads.
  • The web application should show advertisements so that hosting costs could be compensated.

This project was intended to let me learn the basic concepts of modern web application. Looking back, I feel that one major thing that is missing here is some sort of user authentication. I simply did not take my time for that yet.

The Development Environment

To get things going I started to develop on my local machine. Basically, you can start developing with the MEAN stack components if you have your favorite text editor and an open command shell. I used my favorite editor Sublime Text together with the MacOS terminal. You can find quite a lot of helpful plugins for Sublime Text that support web application development, just search the package directory, e.g., for JSFormat, JSHint, JavaScriptNext, or Angular, and you will get an efficient development environment in minutes. Of course, there are loads of specialized integrated development environments (IDEs) for JavaScript projects. JetBrains Webstorm is one of those IDEs that tried out and I must say that I got a good impression of that tool. However, I wanted to keep the costs as low as possible for this project and, in the end, I preferred the slim and much cheaper combination of Sublime Text and the terminal.

Also, CodePen.io often turned out to be a valuable source of information with online functionalities: It allows you to experiment with code snippets directly on their website without further delay. An early example of an Angular front-end that I looked at was this one.

Rapid Development with a Framework: The MEAN Stack

After I set up the list of use cases that the web application must fulfill I started to try and get an overview about present frameworks for web application development. There is a myriad of web frameworks. In the end I decided to use the frameworks, which the MEAN stack comprises:

From a deployment point-of-view you can image the MEAN stack in this way:

Node.js provides the core server functionalities, takes care for the HTTP and HTTPS connections, and handles all the server-side computations. Express makes makes the web server part even easier. MongoDB is used for statistic counters in this application, which is far beyond the capabilities of MongoDB, I know. But it was a nice application for learning MongoDB together with Node.js. AngularJS runs on the user’s local machine and takes care for the front-end logic.

What I particularly like about the MEAN stack is the fact that you can use the same programming language, JavaScript, throughout your whole project. Valeri Karpov from MongoDB tells it in this way and I fully agree with it:

[…] we can store our documents in a JSON-­like format, write JSON queries on our ExpressJS and NodeJS based server, and seamlessly pass JSON documents to our AngularJS frontend. Debugging and database administration become a lot easier when the objects stored in your database are essentially identical to the objects your client Javascript sees. Even better, somebody working on the client side can easily understand the server side code and database queries; using the same syntax and objects the whole way through frees you from having to consider multiple sets of language best practices and reduces the barrier to entry for understanding your codebase. […]

With the application and the decision for the MEAN stack in mind, how did I continue? Besides web resources, I got some books that helped me with that at the beginning:

  • Node.js, MongoDB, and AngularJS Web Development
    This book gives an insight into every component of the MEAN stack and provides a lot of examples that can directly be tested out. The book was a bit overwhelming in the first read, which might also come from the not so perfect layout, and I turned to additional resources. However, I began to look into that book again during the development after I become more and more familiar with the individual frameworks. Especially the section about “Practical Web Application Components” that gives complete examples (including all MEAN components) turned out to be very useful in my case.
  • Node.js Design Patterns
    As the book states in the introductory part, it is intended for developers that have already had first contact with node and finished some smaller Node.js projects. This books helps you to further improve your code and gives you hints and tweaks for various aspects of Node.js. For a beginner I must say that this book is not the first choice for getting to know the MEAN stack. But if you turn to that book with special questions that arise during the Node.js development it is a helpful resource.

Here is an exemplary overview about the interaction between the different components when the user generates a new letter document: When the user clicks the ‘generate’ button or changes one of the input fields, the PDF of the letter is updated. This is process is shown in the following diagram:

The following sections give some more details about the resources that I used when I dealt with the different MEAN stack components for this project.

Node.js as Server-Side Runtime Environment

As I mentioned above, in the first phase I developed solely on my local machine. Therefore, I only had to install Node.js, which is easily done with the installer available on the Node.js download site. If you later want to set up a Node.js web application server, DigitalOcean provides a well-written tutorial about this. Also for the deployment on the web application server, I found the other tutorial form DigitalOcean about PM2 helpful. At this point I also would like to mention Node’s package manager NPM that I have used a lot and that made me more than one time say ‘wow, so easy’ during the work on this project. It is fascinating to see how many packages for all kinds of applications exists for Node.js.

A Web Application in Seconds: The Express Framework

Node.js already comes with modules that provide a basic framework to implement HTTP and HTTPS servers easily. While these modules are quite low level, there is the Express module that

[…] extends the functionality of the http module by making it easy […] to handle server routes, responses, cookies, and HTTP request statuses. (from: Node.js, MongoDB, and AngularJS Web Development)

Setting up an HTTP and HTTPS server with Node, Express, and MongoDB connection with authentication took me around 30 lines of code and I bet that this could even be smaller with a bit more knowledge about Node. To get an SSL certificate for the server, I used the service offered by StartSSL. I made good experiences with that service and I got my certificate within minutes.

Express made it very easy to create a REST API. Basically, the definition of the routes looks like

app.get(/api/v1/letter/get/pdfcounter,letters.getCounterPDF); (1)
app.post(/api/v1/letter/get/pdf,letters.getPDF); (2)

Here, line (1) defines a route for getting a counter that returns the total number of PDFs generated with the letter service. The function ‘getCounterPDF’ accesses the MongoDB for this. Line (2) defines a route that allows to post letter JSON data and returns a PDF as result of the LaTex compiler.

Managing Data with MongoDB

The database plays only a minor role for this web application, because the application is not supposed to save any letter information. For learning purposes it is used to collect some usage statistics: It counts the number of generated documents per month and year.

To get things running with MongoDB I have followed these steps:

  1. Installation of MongoDB
    You can find many examples and tutorial about the installation of MongoDB in the web. I followed this one for the first installation, basic configuration, and getting to know some rudimentary steps.
  2. Installation of a (remote) MongoDB administration client
    MongoDB provides a command shell that gives you the abilities to fully administrate it. If you are looking for a graphical user interface for that task, you — again — have the choice between a plethora of tools. Among those, I found that MongoChef provides exactly those functionalities that I was looking for: Remote connections to a MongoDB installation, queries, and administration with a well organized GUI. For technical questions StackOverflow helped me with details about the MongoDB configuration for remote connections to MongoDB databases.
  3. Installation of the Node.js MongoDB driver
    In order to access a MongoDB database from within Node.js you need to install a driver. This is done with a single command by using the Node Package Manager (NPM).
  4. Installation and Usage of Mongoose
    Mongoose provides elegant MongoDB object modeling and allows you, e.g., to generate and work with model schema definitions, data models and their operations, as well as data validation. Like a facade you can imagine Mongoose to be an additional layer between MongoDB and your application that eases the usage of MongoDB databases. The installation and basic usage of Mongoose went quite well, except one thing: I realized that not all versions of Node.js, MongoDB, and the Node.js driver for MongoDB are compatible with each other. If you are running into these problems and you happen to follow some online tutorial, it is best to install exactly those versions that are mentioned in the tutorial then.

At this point of the development I found the various tutorials from Simon Holmes very helpful. They are not only about MongoDB, but about the MEAN stack in general and I can recommend to read them.

Where is the Front-End? Angular.js and Angular Material

So, Node.js together with Express and MongoDB are working on the back-end side of the application. What about the front-end? Here, we make use of AngularJS, a framework that allows you to use HTML templates to describe the views of your application. Angular synchronizes the data of the views with your Javascript models through two-way binding. Controllers, Factories, Services, and Dependency Injection are further core components of AngularJS, which are supposed to support the developer to structure the application and make it easy to maintain and test. I discovered the AngularJS tutorial site quite recently and got the impression that it might also be a good starting point for getting to know AngularJS.

When I started with the front-end development I quickly realized that I would need some sort of user-interface library so that I would not need to define the look-and-feel of the views from scratch. I looked especially for something that was fitted to AngularJS and I found Angular Material. Angular Material is an implementation of Google’s Material Design Specification and plays nicely together with AngularJS. The Demos Section of the Angular Material website turned out to be very helpful. Another helpful resource was the book “Unraveling Angular Material“. Besides other things the book helped me to get ideas about how to organize the files for the front-end.

Icons became another issue — where should I get them from? A quick web search did it and I found the great website Font Awesome that offers free icons of all possible kinds.

Another great thing about Angular is its huge community. You can find components for all kinds of things; Google and Github are your friend here. Here is a list of components that I am currently using for this LaTex application:

  • AngularJS PDF
    An AngularJS directive to display PDF files with the help of the Javascript library PDFJS.
  • Angular Disqus
    A directive to embed a Disqus comments widget on your AngularJS page.
  • ngAdsense
    An AngularJS directive to display Google AdSense advertisements.
  • Angular Google Analytics
    This service lets you integrate google analytics tracker in your AngularJS applications.

I think that good user-interface design is a complex task. I am no expert in UI design, but I at least wanted to try and come up with something that would be a good basic UI without big annoyances. After creating a basic idea of the UI for the application, I spent hours to learn the basics of Angular and Angular Material. Then I started to think about refinements for the initial drafts of the user interface. I made quite a progress regarding its usability. During that process I got to know the developer tools and especially the debuggers of Safari and Chrome quite well. Even though there are a few things that I still would like to enhance, I reached the point were I decided to keep the UI in its current state (at least for now).

Overall, I can enjoy the work with Angular and Angular Material. As soon as you have mastered the basic concepts and ideas of these libraries it is very easy to come up with a modern looking UI for your front-end.

Some Screenshots of the Final Web Site

Here are some screenshots of the site to give you an idea about the look:

Click to view slideshow.

Conclusion

With this project I learned the basics of web applications based on the MEAN stack. The presented application provides an assistant for letter writing and makes use of the LaTex word processor on the server site. It can be found at www.texwriting.com. In this article I presented the main use cases of that application and I gave you an overview about the different components of that system together with the various resources that I used to realize everything.

Working with a single programming language on all components of the system was something that I had not experienced in other projects so far. I enjoyed it! The concept of the MEAN stack worked well for this application. For sure, I am still a beginner when it comes to all the used frameworks, but at the same time I am already feeling able to start with other web application projects and to realize new ideas!

What did I left out so far? User authentication is one thing. Satellizer seems to be an interesting option to get this done. Also, I did not take a deeper look at creating unit tests for the Angular components or for the Node.js components of the system.

By the way: If you wonder were the UML diagrams in this article come from, I can tell you that I liked to work with the MEAN stack so much that I decided to start another small project: An UML assistant that allows you to create and share UML diagrams based on PlantUML. But I will write about this in the next post …

I hope you enjoyed this article, learned or found something in it. Feel free to use the comments below to give feedback or ask questions!

]]>
http://blog.petrockblock.com/2015/12/05/getting-to-know-the-mean-stack-with-a-latex-web-application/feed/ 3