MJSAPI

Dependencies

• Apache2 with PHP, htaccess and mod_rewrite. Another webserver with PHP support can work, but then the redirects in .htaccess might need to be ported to it.
• PHP module: sqlite3

On Debian, this can be achieved with;

apt install apache2  libapache2-mod-php php-sqlite3
sudo a2enmod rewrite
sudo tee /etc/apache2/conf-enabled/local-allow-htaccess-rewrite.conf <<EOF
<Directory /var/www/>
  AllowOverride FileInfo AuthConfig Limit Indexes
</Directory>
EOF
sudo systemctl restart apache2

Setup

1. Clone git repository inside the Apache documentroot and make the directory writable by PHP. E.g.:

   sudo mkdir /var/www/html/mjsapi
   sudo chown "$USER" /var/www/html/mjsapi
   git clone https://src.giplt.nl/harmen/mjsapi.git /var/www/html/mjsapi
   sudo chown "www-data" /var/www/html/mjsapi
   

   This first creates the directory writable to your current user (so you do not need to run git as sudo), and then changes the directory ownership to allow PHP to create the database.

2. Copy config.template to config.json and fill in config values:

   • systemEmailName and systemEmailAddress: Used as the sender of outgoing e-mails.
   • sqliteUserDatabase: Path to the database file. It will be created and filled when it does not exist yet.
   • JWT_KEY: This must be a random value with at least 256 bits (matching the HS256 algorithm used) of randomness (32 bytes). It can be a raw binary value, ASCII string or hex string. For example, generate with: openssl rand -hex 32.
   • ttnBaseUrl and ttnServe indicate the TTN API and server to use, adapt the defaults to the region you are using.
   • ttnApiKey is an API key generated on the TTN console for the application used. Needed permissions: "view devices in application", "view device keys in application", "create devices in application", "edit device keys in application". TODO: This does not seem to be enough, so select "all rights" for now.
   • ttnApId: The ID of the TTN application to add nodes to.
   • ttnJoinEUI: The join / application EUI that the device will use. This should be a hex-encoded big-endian EUI (16 hex characters).
   • ttnIdPrefix: This is a prefix added before the node number to generate the TTN device id.

Register user manually

1. Register account:

   API=http://localhost/mjsapi
   curl -i -d '{"email": "email@example.org"}' -X POST "$API/users"
   

2. Extract the key from the e-mail (get only the numbers).

3. Login with key:

   curl -i -d '{"email": "email@example.org", "key": "12345678"}' -X POST "$API/users/authkey"
   

4. Extract the JWT from the response and use that to authenticate further requests (e.g.):

   JWT=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiZGlzcGxheV9uYW1lIjoiTXkgTmFtZSIsImVtYWlsIjoibWF0dGhpanNAc3RkaW4ubmwiLCJhZG1pbiI6MSwiaWF0IjoxNzM0NDU0MTA2fQ==.MTU5ODQ1NmQ2MGFjMTFkNTEwY2EwODU5YmRlNzhhZmVkZTM4ZTg1YzMwMjRlNDFjMjlkNGJkOWNiNDU3MTMxMw==
   
   curl -i -H "Authorization: JWT $JWT" -X GET "$API/users"
   

5. Optionally set a password and other user details:

   curl -i -H "Authorization: JWT $JWT" -d '{"password": "foo", "display_name": "My Name"}' -X PUT "$API/users/1"
   

6. Optionally login with password:

   curl -i -d '{"email": "email@example.org", "password": "foo"}' -X POST "$API/users/authpwd"
   

Register node manually

1. Register node:

   API=http://localhost/mjsapi
   curl -i -H "Authorization: JWT $JWT" -X POST "$API/nodes/register"
   

2. Extract the node id from the response and request info and credentials:

   ID=3000
   curl -i -H "Authorization: JWT $JWT" -X GET "$API/nodes/$ID"
   curl -i -H "Authorization: JWT $JWT" -X GET "$API/nodes/$ID/credentials"
   

3. List all your nodes (or all nodes if you are admin):

   curl -i -H "Authorization: JWT $JWT" -X GET "$API/nodes"