do not communicate the 'generic-' part to the user; add commands from #…

…338 work to getting-stated guide; add commands to CLI reference

Signed-off-by: Nicolas Höning <nicolas@seita.nl>

documentation/cli/change_log.rst

@@ -8,8 +8,8 @@ FlexMeasures CLI Changelog
 since v0.9.0 | January 26, 2022
 =====================
 
-* add ``flexmeasures add sensor``, ''flexmeasures add generic-asset-type``, ``flexmeasures add generic-asset`` and ``flexmeasures add beliefs``. These were previously experimental features (under the `dev-add` command group).
-* delete ``flexmeasures add asset``. Use ``flexmeasures add generic-asset`` instead.
+* add ``flexmeasures add sensor``, ''flexmeasures add asset-type``, ```flexmeasures add beliefs``. These were previously experimental features (under the `dev-add` command group).
+* ``flexmeasures add asset`` now directly creates an asset in the new data model.
 
 
 since v0.6.0 | April 2, 2021

documentation/cli/commands.rst

@@ -28,9 +28,11 @@ of which some are referred to in this documentation.
 ``flexmeasures add account-role``                 Create a FlexMeasures tenant account role.
 ``flexmeasures add account``                      Create a FlexMeasures tenant account.
 ``flexmeasures add user``                         Create a FlexMeasures user.
-``flexmeasures add asset``                        Create a new asset.
+``flexmeasures add asset``                        Create a new asset type.
+``flexmeasures add asset-type``                   Create a new asset.
 ``flexmeasures add weather-sensor``               Add a weather sensor.
 ``flexmeasures add external-weather-forecasts``   Collect weather forecasts from the DarkSky API.
+``flexmeasures add beliefs``                      Load beliefs from file.
 ``flexmeasures add forecasts``                    Create forecasts.
 ================================================= =======================================
 

documentation/getting-started.rst

@@ -147,15 +147,17 @@ Add your first asset
 
 There are three ways to add assets:
 
-Use the ``flexmeasures`` :ref:`cli`:
+First, you can use the ``flexmeasures`` :ref:`cli`:
 
 .. code-block::
 
-    flexmeasures add generic-asset --name "my basement battery pack" --generic-asset-type-id 3 --latitude 65 --longitude 123.76 --account-id 2
+    flexmeasures add asset --name "my basement battery pack" --asset-type-id 3 --latitude 65 --longitude 123.76 --account-id 2
 
-For the ownership, I got my account ID from the output of ``flexmeasures add account`` above, or I can browse to `FlexMeasures' user listing <http://localhost:5000/users>`_ and hover over my username.
+For the account ID, I consult ``flexmeasures show asset-types``.
 
-Or, you could head over to ``http://localhost:5000/assets`` (after you started FlexMeasures, see step "Run FlexMeasures" further down) and add a new asset there in a web form.
+For the account ID, I looked at the output of ``flexmeasures add account`` (the command we issued above) ― I could also have consulted ``flexmeasures show accounts``.
+
+The second way to add an asset is the UI ― head over to ``https://localhost:5000/assets`` (after you started FlexMeasures, see step "Run FlexMeasures" further down) and add a new asset there in a web form.
 
 Finally, you can also use the `POST /api/v2_0/assets <api/v2_0.html#post--api-v2_0-assets>`_ endpoint in the FlexMeasures API to create an asset.
 
@@ -167,9 +169,11 @@ Usually, we are here because we want to measure something with respect to our as
 
 .. code-block::
 
-   flexmeasures add sensor --name power --unit MW --event-resolution 5 --timezone Europe/Amsterdam --generic-asset-id 1 --attributes '{"capacity_in_mw": 7}'
+   flexmeasures add sensor --name power --unit MW --event-resolution 5 --timezone Europe/Amsterdam --asset-id 1 --attributes '{"capacity_in_mw": 7}'
+
+The asset ID I got from the last CLI command, or I could consult ``flexmeasures show account --account-id <my-account-id>``.
 
-Capacity is something unique to power sensors, so it is added as an attribute.
+.. note: The event resolution is given in minutes. Capacity is something unique to power sensors, so it is added as an attribute.
 
 
 Run FlexMeasures
@@ -193,19 +197,19 @@ When you see the dashboard, the map will not work. For that, you'll need to get
 Add data
 ^^^^^^^^
 
-You can use the `POST /api/v2_0/postMeterData <api/v2_0.html#post--api-v2_0-postMeterData>`_ endpoint in the FlexMeasures API to send meter data.
+There are three ways to add data:
 
-.. note::  `issue 56 <https://github.com/FlexMeasures/flexmeasures/issues/56>`_ should create a CLI function for adding a lot of data at once, from a CSV dataset.
-
-Also, you can load in data from a file (CSV or Excel) with the ``flexmeasures`` :ref:`cli`:
+First, you can load in data from a file (CSV or Excel) via the ``flexmeasures`` :ref:`cli`:
 
 .. code-block::
    
    flexmeasures add beliefs --file my-data.csv --skiprows 2 --delimiter ";" --source OurLegacyDatabase --sensor-id 1
 
 This assumes you have a file `my-data.csv` with measurements, which was exported from some legacy database, and that the data is about our sensor with ID 1. This command has many options, so do use its ``--help`` function.
 
-Finally, you can tell FlexMeasures to create forecasts for your meter data with the ``flexmeasures add`` command, here is an example:
+Second, you can use the `POST /api/v2_0/postMeterData <api/v2_0.html#post--api-v2_0-postMeterData>`_ endpoint in the FlexMeasures API to send meter data.
+
+Finally, you can tell FlexMeasures to create forecasts for your meter data with the ``flexmeasures add forecasts`` command, here is an example:
 
 .. code-block::
 
@@ -245,3 +249,11 @@ Install and configure Redis
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 To let FlexMeasures queue forecasting and scheduling jobs, install a `Redis <https://redis.io/>`_ server (or rent one) and configure access to it within FlexMeasures' config file (see above). You can find the necessary settings in :ref:`redis-config`.
+
+
+Where to go from here?
+------------------------
+
+If your data structure is good, you should think about (continually) adding measurement data. This tutorial mentioned how to add data, but :ref:`_tut_posting_data` goes deeper with examples and terms & definitions.
+
+Then, you probably want to use FlexMeasures to generate forecasts and schedules! For this, read further in :ref:`_tut_forecasting_scheduling`. 

flexmeasures/cli/data_add.py

@@ -157,7 +157,8 @@ def new_user(
     help="timezone as string, e.g. 'UTC' or 'Europe/Amsterdam'",
 )
 @click.option(
-    "--generic-asset-id",
+    "--asset-id",
+    "generic_asset_id",
     required=True,
     type=int,
     help="Generic asset to assign this sensor to",
@@ -195,25 +196,25 @@ def add_sensor(**args):
     print(f"You can access it at its entity address {sensor.entity_address}")
 
 
-@fm_add_data.command("generic-asset-type")
+@fm_add_data.command("asset-type")
 @with_appcontext
 @click.option("--name", required=True)
 @click.option(
     "--description",
     type=str,
     help="Description (useful to explain acronyms, for example).",
 )
-def add_generic_asset_type(**args):
-    """Add a generic asset type."""
+def add_asset_type(**args):
+    """Add an asset type."""
     check_errors(GenericAssetTypeSchema().validate(args))
     generic_asset_type = GenericAssetType(**args)
     db.session.add(generic_asset_type)
     db.session.commit()
-    print(f"Successfully created generic asset type with ID {generic_asset_type.id}")
-    print("You can now assign generic assets to it")
+    print(f"Successfully created asset type with ID {generic_asset_type.id}.")
+    print("You can now assign assets to it.")
 
 
-@fm_add_data.command("generic-asset")
+@fm_add_data.command("asset")
 @with_appcontext
 @click.option("--name", required=True)
 @click.option(
@@ -228,19 +229,20 @@ def add_generic_asset_type(**args):
 )
 @click.option("--account-id", type=int, required=True)
 @click.option(
-    "--generic-asset-type-id",
+    "--asset-type-id",
+    "generic_asset_type_id",
     required=True,
     type=int,
-    help="Generic asset type to assign to this asset",
+    help="Asset type to assign to this asset",
 )
-def add_generic_asset(**args):
-    """Add a generic asset."""
+def add_asset(**args):
+    """Add an asset."""
     check_errors(GenericAssetSchema().validate(args))
     generic_asset = GenericAsset(**args)
     db.session.add(generic_asset)
     db.session.commit()
-    print(f"Successfully created generic asset with ID {generic_asset.id}")
-    print("You can now assign sensors to it")
+    print(f"Successfully created asset with ID {generic_asset.id}.")
+    print("You can now assign sensors to it.")
 
 
 @fm_add_data.command("weather-sensor")