README.md

The NGSI Go is a command-line interface supporting FIWARE Open APIs for FIWARE developers.

📚 Documentation	🎯 Roadmap

Contents

Details

• Getting Started with NGSI Go
• Usage
• Tutorial
• Install
• Third party packages
• Copyright and License

What is NGSI Go?

"Brave (hero), bearer of the blood of Erdrick, hero of legend! Know that your weapon will not serve to vanquish the Dragonload."

— DRAGON WARRIOR (DRAGON QUEST)

The NGSI Go is a command-line interface supporting FIWARE Open APIs, which simplifies syntax. It's a powerful tool and easy to use. It has various features as shown:

• Supported FIWARE Open APIs
  • FIWARE NGSI v2 API
  • NGSI-LD API
  • STH-Comet API
  • QuantumLeap API
  • Cygnus API
  • IoT Agent Provision API
  • Perseo API
  • Keyrock API
  • WireCloud API
• Various convenience commands
  • NGSI commands to manage NGSI Entity, subscription, registration and so on
  • Time series commands to manage historical data
  • IoT Agent commands to manage IoT Agent Provision API
  • Rules commands to manage Context-Aware CEP
  • WireCloud command to manage Application Mashup RESTful API
  • Convenience commands
    • Print version, health-check status and API lists of FIWARE GEs
    • Admin command for FIWARE Orion
    • Copy and remove entities at once
    • Create template of subscription or registration
    • Notification receiver
    • Registration proxy
  • Management commands
    • Broker alias or server alias with API endpoint URL, FIWARE Service and FIWARE ServicePath
    • Manage @context
    • Integrated oauth token management
• Compatible with a number of traditional UNIX commands for filtering text
• A single binary program written in Golang

Getting Started with NGSI Go

You register an alias to access the broker.

ngsi broker add --host letsfiware --brokerHost http://localhost:1026 --ngsiType v2

You can get the version by using the alias letsfiware.

ngsi version -h letsfiware

{
"orion" : {
  "version" : "3.7.0",
  "uptime" : "0 d, 0 h, 0 m, 1 s",
  "git_hash" : "8b19705a8ec645ba1452cb97847a5615f0b2d3ca",
  "compile_time" : "Thu May 26 11:45:49 UTC 2022",
  "compiled_by" : "root",
  "compiled_in" : "025d96e1419a",
  "release_date" : "Thu May 26 11:45:49 UTC 2022",
  "machine" : "x86_64",
  "doc" : "https://fiware-orion.rtfd.io/en/3.7.0/",
  "libversions": {
     "boost": "1_74",
     "libcurl": "libcurl/7.74.0 OpenSSL/1.1.1n zlib/1.2.11 brotli/1.0.9 libidn2/2.3.0 libpsl/0.21.0 (+libidn2/2.3.0) libssh2/1.9.0 nghttp2/1.43.0 librtmp/2.3",
     "libmosquitto": "2.0.12",
     "libmicrohttpd": "0.9.70",
     "openssl": "1.1",
     "rapidjson": "1.1.0",
     "mongoc": "1.17.4",
     "bson": "1.17.4"
  }
}
}

Once you access the broker, you can omit to specify the broker.

ngsi version

If you want to check the current settings, you can run the following command.

ngsi settings list

Usage

NAME:
   ngsi - command-line tool for FIWARE Open APIs

USAGE:
   ngsi [global options] command [options] [arguments...]

VERSION:
   ngsi version 0.13.0 (git_hash:8aeaca431eb3c46f160be043ab865f8c58b26389)

COMMANDS:
   help, h  Shows a list of commands or help for one command
   APPLICATION MASHUP:
     preferences  manage preferences for WireCloud
     macs         manage mashable application components for WireCloud
     workspaces   manage workspaces for WireCloud
     tabs         manage tabs for WireCloud
   Context-Aware CEP:
     rules  rules command for PERSEO
   CONVENIENCE:
     admin       admin command for FIWARE Orion, Cygnus, Perseo, Scorpio
     apis        print endpoints of API
     cp          copy entities
     wc          print number of entities, subscriptions, registrations or types
     man         print urls of document
     health      print health status
     ls          list entities
     queryproxy  query proxy
     rm          remove entities
     receiver    notification receiver
     regproxy    registration proxy
     template    create template of subscription or registration
     tokenproxy  token proxy
     version     print the version
   IoT Agent:
     devices   manage devices for IoT Agent
     services  manage services for IoT Agent
   Keyrock:
     applications   manage applications for Keyrock
     users          manage users for Keyrock
     organizations  manage organizations for Keyrock
     providers      print service providers for Keyrock
   NGSI:
     append   append attributes
     create   create entity(ies), subscription, registration or ldContext
     delete   delete entity(ies), attribute, subscription, registration or ldContext
     get      get entity(ies), attribute(s), subscription, registration type or ldContext
     list     list types, attributes, entities, tentities, subscriptions or registrations
     replace  replace entities or attributes
     update   update entities, attribute(s) or subscription
     upsert   upsert entity or entities
   PERSISTING CONTEXT DATA:
     namemappings   manage namemappings for Cygnus
     groupingrules  manage groupingrules for Cygnus
   TIME SERIES:
     hdelete  delete historical raw and aggregated time series context information
     hget     get historical raw and aggregated time series context information
   MANAGEMENT:
     broker    manage config for broker
     context   manage @context
     settings  manage settings
     server    manage config for server
     token     manage token
     license   print OSS license information

GLOBAL OPTIONS:
   --syslog LEVEL        syslog logging LEVEL (off, err, info, debug)
   --stderr LEVEL        stderr logging LEVEL (err, info, debug)
   --configDir DIR       configuration DIR name
   --config FILE         configuration FILE name
   --cache FILE          cache FILE name
   --batch, -B           don't use previous args (batch) (default: false)
   --insecureSkipVerify  TLS/SSL skip certificate verification (default: false)
   --help                show help (default: false)
   --version, -v         print the version (default: false)

PREVIOUS ARGS:
   None

Tutorial

You can try the tutorial to understand how to use the NGSI Go. You need a environment running Docker engine and docker-compose.

Install

Install NGSI Go binary

The NGSI Go binary is installed in /usr/local/bin.

Installation on Linux

curl -OL https://github.com/lets-fiware/ngsi-go/releases/download/v0.13.0/ngsi-v0.13.0-linux-amd64.tar.gz
sudo tar zxvf ngsi-v0.13.0-linux-amd64.tar.gz -C /usr/local/bin

ngsi-v0.13.0-linux-arm.tar.gz and ngsi-v0.13.0-linux-arm64.tar.gz binaries are also available.

Installation on Mac

curl -OL https://github.com/lets-fiware/ngsi-go/releases/download/v0.13.0/ngsi-v0.13.0-darwin-amd64.tar.gz
sudo tar zxvf ngsi-v0.13.0-darwin-amd64.tar.gz -C /usr/local/bin

ngsi-v0.13.0-darwin-arm64.tar.gz binary is also available.

Install bash autocomplete file for NGSI Go

Install ngsi_bash_autocomplete file in /etc/bash_completion.d.

curl -OL https://raw.githubusercontent.com/lets-fiware/ngsi-go/main/autocomplete/ngsi_bash_autocomplete
sudo mv ngsi_bash_autocomplete /etc/bash_completion.d/
source /etc/bash_completion.d/ngsi_bash_autocomplete
echo "source /etc/bash_completion.d/ngsi_bash_autocomplete" >> ~/.bashrc

Third party packages

The NGSI Go makes no use of third-party packages.

• Open Source Insights

Copyright and License

Copyright (c) 2020-2024 Kazuhito Suda
Licensed under the MIT License.