This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

From Maker to Maker

The 2log documentation is being created here little by little. The documentation was written with the goal to enable Fablabs and Makerspaces to use and operate the 2log system on their own.

All hardware components were intentionally designed based on through-hole parts to allow less experienced makers to solder the parts together.

Feedback welcome!

If any points are not described in enough detail I am grateful for any feedback. Pull requests are welcome.

1 - Overview

What is 2log?

2log is a free community management system for workshops, fablabs, maker- and hackerspaces.

It is a modular hardware and software solution that digitally links machines, users and processes and makes them remotely trackable. Each device with a power cable - from the laser cutter to the coffee machine - can be connected to your 2log instance with the 2log Switch within a few minutes.

Your advantages:

  • Protect the machines from unauthorized use thanks to individual usage authorizations.
  • Bill machine run time either as a flat rate or by the second based on time of use.
  • Transfer your existing machinery to 2log. No changes to the machines are necessary - the manufacturer‘s warranty for the equipment is retained.
  • Reduce your power consumption. Unused machines switch off automatically.
  • Receive statistics on the use of your machines. With 2log you can monitor the load in real time. You can see at any time who has been working on which machine when and where.
  • Use the 2log admin app or the web platform to always have a full overview of the processes in your workshop.
  • Integrate 2log into your existing systems (e.g. CoBot).
  • Bill products like coffee or snacks with a self service terminal.
  • Easy authentication via RFID cards or with with the 2log App by scanning QR Codes.

How it works

In order to integrate a machine into 2log, no structural changes need to be made. The 2log switch is simply plugged between the power plug of the machine and the socket. The setup process is so simple that you can easily do it yourself in minutes.

image

Where should I go next?

2 - Getting Started

Here you will learn step by step how to set up your own 2log instance.

Preamble

2log is a free OpenSource project that can be used freely and without charge under the terms of the GPL v.3/ AGPL v.3. This means that the authors of 2log.io do not accept any liability for any damage or infringement of valid rights caused by the use of 2log.io.

Prerequisites

In order to operate 2log, certain technical requirements must be met.

Server and Network

To run your own 2log instance, a Docker-enabled computer with x86-64 architecture is recommended. Since 2log is implemented in a very resource-efficient way, a headless Linux server with a 1.4GHz dual core and 4GB memory is sufficient.

The 2log hardware components communicate with the server via WiFi. Accordingly, the server and the IoT devices must be able to reach each other over a 2.4GHz network.

For the operation of 2log the server must be able to send e-mails. For this purpose, an SMTP mail server is required.

Machines and devices

Since the 2log Switch controls access to the devices by connecting and disconnecting power, it is important to ensure that all connected machines can handle this. Since 2log detects via power consumption whether the machine is in stand-by mode or actually working, it is ensured that a machine is never switched off from operation.

Depending on the smart sockets used for the 2log switches, it must be ensured that the machines do not draw more current than is supported by the connectors.

2.1 - Setup the 2log.io Server Application

Learn how to set up a 2log instance

The easiest way to set up your 2log instance is to use Docker.

Using Docker

The easiest way to set up your 2log instance is to use the Dockerfile provided in the repository. First, make sure that Docker is installed with the associated tool docker-compose.

mkdir ~/2log
cd 2log
wget https://gitlab.com/2log-io/2log.io/-/raw/main/docker/docker-compose.yaml
docker-compose up

By default, the WebAssembly frontend can be reached via Port 8080. If the server is running on your local machine, just visit http://localhost:8080 in your web browser and the UI should come up. You can now login into your instancy by accessing the WebSocket service which is by default accessible via port 4711. To check your instance is up and just type ws://localhost:4711. The initial default login is “admin” with passwort “password”. Don’t forget to change the password after the first login!

Setup Mail Server

The mail server can be configured directly via the environment variables. The easiest way to define these settings is directly in the docker-compose file.

#--------- Mail Server config
#- MAIL_HOST=smtp.mydomain.com
#- MAIL_USER=admin
#- MAIL_PASS=password
#- MAIL_ADDR=2log@mydomain.com //sender eMail address
#- MAIL_CONNECTION_TYPE=TLS // or SSL or TCP
#- MAIL_SENDER=2log.io // readable sender name (optional)
#- MAIL_PORT=587
Variable Description Example
MAIL_HOST How to reach the mailserver smtp.mydomain.com
MAIL_USER The login string admin
MAIL_PASS The mail server password xF5s42F1337@r!
MAIL_ADDR Sender eMail Adesse 2log@mydomain.com
MAIL_CONNECTION_TYPE Security settings. Supported are TLS, SSL or TCP TLS
MAIL_PORT The port where the mail server is listening 587

Update the 2log.io instance

To get the latest features and bug fixes it is recommended to update the 2log server regularly.

Updating the 2log instance when using the Docker Compose file is very simple. Just enter the following commands in the command line:

docker-compose pull 2log
docker-compose up

Backup data

All operational data of the 2log instance is stored in the folder ./2log.io. It is strongly recommended to back up the folder at regular intervals.

2.2 - Let your community grow!

Learn how to add or import members to your 2log.io instance

To add new members you can either use the web portal or the 2log Admin app.

2log has two separate user administrations. Members and administrators are managed separately and independently. This page is only about adding members.

Add a single member

The easiest way to add a new member is via the app or web portal. The procedure is identical for both variants.

  1. Log in to your 2log instance with your admin account.
  2. Switch to the “User” menu item
  3. Click “New user”
  4. Fill in the form fields.
    • The alias field is optional. The alias must be unique and can be used by the members besides the email address to log in. If there is already a user with this alias, an error message will be displayed. The alias can also be used to call the user by his nickname.
    • The eMail address is mandatory and must be unique. If there is already a user with this email address, an error message will be displayed.
    • Currently there are three different roles: “Member”, “employee” and “guest”. Unlike “employee”, “guest” is not yet used productively. The role Employee is relevant for the machine time accounting where there is the option “Free for employees”.
  5. In the “Account balance” box, a starting balance can be set and an RFID card can be added.
    • If you use the app on an RFID-enabled smartphone, you can scan the new card directly with your phone.
    • Alternatively, the use of an “Admin Dot” is possible. This can be set up in the “Administration” area and allows convenient reading of cards from the web app.
  6. Grant access rights to individual machines or groups
  7. Click on “Create user”.

Congratulations! This is your first community member.

Add members with the CSV importer

If many users are created at once, for example when the new class starts the semester, the CSV Importer is the better choice.

  1. Log in to your 2log instance with your admin account.
  2. Switch to the “User” menu item
  3. Click “CSV Import”
  4. Download the sample template to see an example of a valid import file.
    • The importer uses the labeling of the header, i.e. the first line, to assign the individual fields. Accordingly, it does not cause any problems if additional fields or a different order is used.
  5. Upload your CSV File. You will now see a preview of the records found.
    • If no role has been assigned yet, you can assign one using the button in the header of the preview. The same applies to the group. It is possible to add a group permission to a record uploaded via CSV.
  6. Confirm the import with a click on “start import”.

2.3 -

3 - Machine Control

Here you will learn how to integrate a machine into 2log.io

One of the main functions of 2log is the access control of machines. A machine can be any device with a power cable. From the laser cutter to the band saw to the 3D printer, pretty much any device can be integrated.Thanks to 2log rights management, each user can be given permission to use specific machines. This is done either via individual permissions or via groups.

Via the power consumption, 2log can determine whether a machine is actually working or only in stand-by mode. In this way, the machine usage can be charged according to different pricing models.

Prerequisities

Certain hardware and software components are required to set up a machine access control.

The machine itself

Since the 2log Switch controls access to the devices by connecting and disconnecting power, it is important to ensure that all connected machines can handle this. Since 2log detects via power consumption whether the machine is in stand-by mode or actually working, it is ensured that a machine is never switched off from operation.

Depending on the smart sockets used for the 2log switches, it must be ensured that the machines do not draw more current than is supported by the smart plugs.

Needed Hardware

To integrate a machine into 2log, two hardware components are required: A 2log Switch and a 2log Dot. The Dot is a smart RFID reader that reads the user’s cards and logs them into the machine. The Swtich is the actuator. It activates the power supply only when a user with valid authorization has logged on to the system.

Used Software

The 2log Admin App is required to connect the hardware components with the 2log.io server. The APK for Android can be downloaded here

3.1 - Setup a Machine Control Instance

Learn how to setup a machine control by connecting Switch and Dot with the 2log system.

Create a new Machine

Connecting the hardware components to the server must be done via the 2log app. This is currently only available for Android. The APK can be downloaded here. For this reason, it is recommended to run the complete setup of the new machine directly via the app.

  1. Log in to your 2log instance with your admin account.
  2. Go to “Resources” and click on “Add” in the “Access control” box in the upper right corner
  3. Enter a unique and preferably unambiguous name for the machine in the small pop-up window and then click on the “+” symbol.
  4. The new machine should now appear as a tile. You will then be taken directly to the machine settings overview page.

Connet a Dot

In the machine settings there is a box with the heading “Dot”. Immediately after creating the machine, a note should appear here stating that no dot has yet been assigned.

  1. Click on “Set up now”
  2. Now you will be asked if you want to use a dot that was already used in the system or if you want to use a new dot.

Setup a new Dot

If you are setting up a new machine you will probably want to connect a new Dot.

  1. Answer “no” to the question whether the Dot is already connected to the system. You will now be redirected to the Setup Wizard.

  2. Follow the instructions dosplayed on the screen until the setup is complete.

  3. If the setup is completed successfully, you have the possibility to test the connection by clicking on the “Blink” button. If the LEDs of the dot start blinking, everything has worked.

Setup an already connected Dot

If it is a Dot that is already connected to the server, continue here.

  1. Answer “yes” to the question whether the Dot is already connected to the system.

  2. Enter the four character address of the dot you want to assign to the machine.

  3. If the setup is completed successfully, you have the possibility to test the connection by clicking on the “Blink” button. If the LEDs of the dot start blinking, everything has worked.

Connect a Switch

In the machine settings there is a box with the heading “Switch”. Immediately after creating the machine, a note should appear here stating that no switch has yet been assigned.

  1. Click on “Set up now”
  2. Now you will be asked if you want to use a switch that was already used in the system or if you want to use a new switch.

Setup a new Switch

If you are setting up a new machine you will probably want to connect a new Switch.

  1. Answer “no” to the question whether the Switch is already connected to the system. You will now be redirected to the Setup Wizard.

  2. Follow the instructions dosplayed on the screen until the setup is complete.

Setup an already connected Switch

If it is a Switch that is already connected to the server, continue here.

  1. Answer “yes” to the question whether the switch is already connected to the system.

  2. Enter the four character address of the switch you want to assign to the machine.

3.2 - Configure a Machine Control

Learn how to configure an access control by setting the current threshold and defining the pricing model.

To access the settings page of a machine control:

  1. click on “Resources” in the main menu
  2. click on the machine you want to configure in the “Access Control” box.
  3. click on “Settings” in the upper right corner

General settings

Display Name

Sets the name with which the machine is displayed in the system. The name should be unique and identify the machine without any doubt.

Bad example: “3D Printer 1” , “3D Printer 2”, “3D Printer 3”.

Good example: “Prusa i3MK3s orange”, ““Prusa i3MK3 black”, “Ultimaker 2”

Switch off after …

Defines after which period of time (in minutes) a machine is automatically switched off if no active job is currently running. This also automatically causes the currently logged in user to be logged out.

Type

Select a machine type. This currently only affects the icon that is displayed in the overview page.

Suction

Many machines require suction to extract sawdust or toxic fumes. But some of them are not able to communicate with the machines they are connected to.

2log offers the possibility to switch a suction with a 2log Switch and assign it to one or more machines. If a user logs on to a machine that is connected to a suction, the suction will automatically switch on. This is especially helpful when several machines share one suction.

Pricing

2log offers different pricing models for charging the machine usage. A distinction is made between billing on the basis of machine usage or on the basis of user session. The distinction which billing basis makes more sense depends primarily on the type of machine. Machines whose jobs have a predefined runtime, such as laser cutters or 3D printers, should be billed according to the duration of use. Machines such as belt grinders or drill presses are better billed according to the session. This prevents the user from switching the machine on and off unnecessarily often.

Regardless of the billing basis, you can choose between a flat fee or billing by duration. The duration of a unit can be freely defined.

According to duration of use

When billing according to the duration of use, only the time during which the machine is actually running is charged.

Flat rate per job

With “Flat rate per job”, the set fee is charged as a flat rate for each time the machine is switched on.

Flat rate per session

In the case of a flat rate per session, the set fee is charged only once for logging on to the machine.

By session time

When billing by session time, the time during which the user is logged in to the machine is billed.

Threshold adjustment

When charging on the basis of machine usage (job duration or flat rate per job), it is very important to set the threshold value to match the machine behavior.

  1. Turn on the machine and let it run in stand-by mode for a few minutes.

  2. Start a job and wait until it has run through or switch on the machine and let it work for some time. You should see the power consumption of the machine in the form of a graph.

  3. Move the threshold with the mouse so that the graph is above the line most of the time during operation.

4 - Build the Hardware Components

Here you will learn how to build the 2log hardware components.

Disclaimer

Software, schematics and building instructions were made to the best of our knowledge. We provide them here free of charge because we think it could be of use.

However, we don’t take any responsibility nor liability for using this software nor for the installation or any tips, advice, videos, etc. given by any member of this site or any related site.

4.1 - Build a 2log Dot

Learn how to build a 2log Dot

The 2log Dot is a smart RFID reader that can read almost all common RFID cards. Its main purpose is to allow users to authenticate themselves with their smart cards in the system. For example, to log on to a machine.

The 2log Dot is based on the ESP32 and the PN532, two components that are used very often in the maker scene and are easy to obtain. Thanks to the modular design and the exposed GPIO pins, the 2log Dot can be extended at will.

The PCB

The 2log Dot board is a joint project which was developed together with the Technik Kultur Saar e.V. - Many thanks to Matthew for this contribution! In this repository you will find Gerber files for the 2log Dot board.

Order the PCB

  1. Go to https://jlcpcb.com
  2. Click on “Instant Quote”
  3. Click on “Add gerber file” and upload the .zip file you can get from here .
  4. Do a few necessary changes (let the other settings as it is):
    • Choose the number of pieces (Quantity)
    • Choose your favorite PCB Color - We prefer black ;)
    • Select the appropriate Layers:
      • L1: 2logDot-F_Cu.gbr
      • L2: 2logDot-In1_Cu.gbr
      • L2: 2logDot-In2_Cu.gbr
      • L2: 2logDot-B_Cu.gbr
  5. Proceed with the checkout and complete the order.

Congratulations - in a few days you will have your 2log Dot boards in your hands!

Get the Parts

The PCB consists of a 4-Layer stack. All required parts are through hole components with the exception of the capacitor C1 which is a combined footprint. Besides the PCB itself you need the following parts:

  • 24 Led WS2812B Ring with 4 contacts (diameter 66mm)
  • SMD Capacitor 5mm diameter, about 10uF
  • (alternative) THT Capacitor, about 10uF
  • Wemos D1 mini ESP32 (ESP8266 will not work)
  • PN532 RFID Reader V3 (red modules, sold under elechouse brand or clones)
  • mini pushbutton (the tiny black/silver ones)
  • (optional) 14 Pin Male and 13 Pin Female 2.54mm Pin Header/Socket for expansion port

Renderings

Assembling

To build a Dot you need a soldering iron with a fine tip, solder and some stranded wire.

I highly recommend using the template that can be clamped between the reader and PCB. This ensures that the LED sits above the PN532. This avoids ugly shadows. you can find the stl file here: https://gitlab.com/2log-io/hardware/2log-dot-case

It’s a good idea to put the ESP loose on the pins first, while soldering the pins tight to the board. This ensures that the ESP can be plugged in later without any problems when it is time for its turn. gi

Next, the button can be soldered on.

Solder the pins to the PN532. Also here it makes sense to insert the pins loosely into the board during soldering. Otherwise it can happen that you solder the pins a little bit crooked. Then they no longer fit into the PCB and you have trouble.

Now you can connect the reader to the board. In between comes the template that we printed out earlier with the 3D printer. Make sure that the recess in the template is positioned so that you have free access to the pins for the LED ring.

Now we can solder the capacitor and take the opportunity to cut off the protruding pins of the PN532.

Next, the ESP can be soldered.

Now we can work on the LED ring. For this I took copper wire and stripped it. Next, the stranded wire is tinned and soldered to the contacts of the LED ring.

Bend the pins upwards and put the ring on the template. Here you have to thread the stranded wire through the holes of the board and solder it from the backside.

Congratulations! You now have a 2log Dot.

The case

The case can be printed with normal PLA. Get the stl files from here. I particularly like the matte look of the Extrudr NX2 black matte. For the lid, simply laser a circle with a diameter of 70.5 mm. The material used for this is BLACK & WHITE 9H04 SC.

Flash the Firmware

  1. Make sure that the drivers for the serial adapter of your ESP32 and the Python tool “esptool.py” is installed.
  2. Then download the latest firmware build from our CI Toolchain here: https://gitlab.com/2log-io/2log-dot/-/jobs/artifacts/main/download?job=build
  3. Connect the dot with a micro usb cable to your PC and flash the binaries with the following command to your ESP:
esptool.py  \
            -b 460800 \
            --before=default_reset \
            --after=hard_reset write_flash \
            --flash_mode dio \
            --flash_freq 40m \
            --flash_size 4MB \
            0x1000 bootloader/bootloader.bin \
            0x10000 2log-Dot.bin \
            0x8000 partition_table/partition-table.bin \
            0xe000 ota_data_initial.bin

You may need to add -p /dev/<serial-adapter> with the path to the serial adapter in case the system can’t detect the serial adapter automatically.

4.2 - Build a 2log Switch

Learn how to build a 2log Switch

The 2log Switch is a smart wireless socket that can switch power and measure energy consumption. It communicates via WiFi with the 2log server and ensures that only authorized users can use the machines. By measuring the power consumption, the system knows exactly how long the machine has been in use.

Supported smart sockets

Theoretically, any tasmota compatible, ESP8266 based WiFi socket is suitable. Depending on the type, the software from our repository has to be adapted a bit.

To turn a smart socket into a 2log Switch, the 2log Switch firmware must be flashed to the device. For this purpose a USB Serial Adapter (FTDI) is required.

Shelly Plug S

Officially supported is currently the model “Shelly Plug S”. By the way, this is also one of the few models for which correct CE certificates could be provided.

To flash a Shelly Plug S socket you have to do the following steps:

  1. Download the firmware binaries from our CI Pipeline
  2. Open the housing of the socket by loosening the screw on the back.
  3. Connect the serial programmer (This blogpost shows how to connect the pins)
  4. Flash the firmware with esptool
    esptool.py \
        --chip esp8266 \
        --port /dev/tty.usbserial-UUT1 \
        --baud 230400 \
        --before default_reset \
        --after hard_reset write_flash \
        -z \
        --flash_mode dio \
        --flash_freq 40m \
        --flash_size 4MB \
        0x0 /build/bootloader/bootloader.bin \
        0x10000 /build/2log-switch.bin \
        0x8000 /build/partitions-single-1MB.bin