{
  "id": "lorcap/micropython-suntime",
  "name": "micropython-suntime",
  "prettyName": "micropython-suntime",
  "description": "Sunrise and sunset time computation for MicroPython",
  "version": "",
  "author": "lorcap",
  "license": "MIT",
  "tags": [],
  "status": "VALID",
  "official": false,
  "source": "https://github.com/lorcap/micropython-suntime",
  "updatedAt": "2026-07-28T07:00:25.802Z",
  "page": "https://checkmim.com/packages/lorcap+micropython-suntime",
  "createdAt": "2026-01-07T15:15:12.769Z",
  "submittedBy": "lorcap",
  "install": {
    "mpremote": "mpremote mip install github:lorcap/micropython-suntime",
    "mip": "import mip; mip.install(\"github:lorcap/micropython-suntime\")"
  },
  "readme": "# Sunrise and Sunset Time\n\nThis library provides an approximated calculation of sunrise and sunset time.\nIt is written in Python and targets the [MicroPython](http://micropython.org)'s\nconstrained environments.\n\nMore specifically, given a `date` and the coordinate pair `(latitude,\nlongitude)` of a place on Earth, this library computes when sun rises above di\nhorizon and when it sets down on that day in that place. Methods are provided\nfor checking whether current time is daytime, nighttime, sunrise or sunset\ntime.\n\n\n## Implementations\n\nThe library consists of two implementations: classes `Sundatetime` and\n`Suntime`. They differ from the input and output data types. The former makes\nuse of standard library's `datetime`: it's easier to use but requires more RAM.\nIf target board resources are constrained, the latter offers a viable solution\nby working with integers.\n\n\n### Class `Sundatetime`\n\nThis class makes use of module `datetime` for expressing input date and output\ntime. The following methods are available to the user:\n\n* `Sundatetime(latitude, longitude, altitude=0)`\n  \n  Arguments *latitude* and *longitude* are floats representing the coordinates\n  of a place on Earth. *altitude* is an integer number for observer's elevation\n  in meters.\n  \n* `Sundatetime.calc_sunrise_sunset(date)`\n  \n  Calculate the sunrise and sunset for the given date. *date* must be an\n  *aware* `datetime.datetime` object in the range [2000-01-01; 2100-01-01).\n  Time information is ignored, whereas time zone `tzinfo` is used to provide\n  meaningful output. The results are cached in `sunrise` and `sunset` instance\n  variables.\n  \n* `Sundatetime.is_daytime(now)` and `Sundatetime.is_nighttime(now)`\n  \n  Argument *now* is an *aware* `datetime.datetime` object representing a point\n  in time. A boolean value is returned whether Sun is above/below the horizon\n  or not, `None` when data are meaningless.\n  \n* `Sundatetime.is_sunrise(now)` and `Sundatetime.is_sunset(now)`\n  \n  Argument *now* is an *aware* `datetime.datetime` object representing a point\n  in time. A boolean value is returned whether *now* matches sunrise/sunset\n  time or not, `None` when data are meaningless.\n\n\nThe following instance variables are accessible:\n\n* `Sundatetime.latitude` and `Sundatetime.longitude`\n  \n  Float numbers for coordinates on Earth.\n  \n* `Sundatetime.altitude`\n  \n  Elevation in meters for observations above the sea horizon. It corrects for\n  both apparent dip and terrestrial refraction.\n  \n* `Sundatetime.sunrise` and `Sundatetime.sunset`\n  \n  They hold `None` when an instance is created, an *aware* `datetime.datetime`\n  after `calc_sunrise_sunset()` is called.\n\n> [!NOTE]\n> `Sundatetime.sunrise` may occur before 00:00 and `Sundatetime.sunset` after\n> 23:59 on calculated *date*. See [Unexpected results](#unexpected-results).\n\n\n\n### Class `Suntime`\n\nThe following class makes use of plain integers for expressing input date and\noutput time. The following methods are available to the user:\n\n* `Suntime(latitude, longitude, altitude=0, timezone=0)`\n  \n  Arguments *latitude* and *longitude* are floats representing the\n  coordinates of a place on Earth. *altitude* is an integer number for\n  observer's elevation in meters. *timezone* is an integer holding the\n  timezone offset from UTC in minutes. The results are cached in\n  `sunrise` and `sunset` instance variables.\n  \n* `Suntime.calc_sunrise_sunset(year, month, day, dst=0)`\n  \n  Calculate the sunrise and sunset for the given year, month and day.\n  *year* must be in the range [2000; 2100). *dst* is an integer holding the\n  offset in minute (usually 60) that accounts for Daylight Saving Time.\n  \n* `Suntime.is_daytime(now)` and `Suntime.is_nighttime(now)`\n  \n  Argument *now* is an integer holding the number of minutes since midnight.\n  A boolean value is returned whether Sun is above/below the horizon or not,\n  `None` when data are meaningless.\n  \n* `Suntime.is_sunrise(now)` and `Suntime.is_sunset(now)`\n  \n  Argument *now* is an an integer holding the number of minutes since midnight.\n  A boolean value is returned whether *now* matches sunrise/sunset time or not,\n  `None` when data are meaningless.\n\n\nThe following instance variables are accessible:\n\n* `Suntime.latitude`  and `Suntime.longitude`\n  \n  Float numbers for coordinates on Earth.\n  \n* `Suntime.altitude`\n  \n  Elevation in meters for observations above the sea horizon. It corrects\n  for both apparent dip and terrestrial refraction.\n  \n`Suntime.sunrise` and `Suntime.sunset`\n  \n  It holds `None` when an instance is created, an integer for the\n  difference in minutes since 00:00 after `calc_sunrise_sunset()`\n  is called.\n\n> [!NOTE]\n> `Suntime.sunrise` may be negative and `Suntime.sunset` may be greater than\n> 1439 (24 hours). See [Unexpected results](#unexpected-results).\n\n\n### Unexpected results\n\nClass `Sundatetime` may return unexpected results: `Sundatetime.sunrise` may\ncome before 00:00 and/or `Sundatetime.sunset` may come after 23:59. Similarly,\nclass `Suntime` may return a negative `Suntime.sunrise` and/or a\n`Suntime.sunset` greater or equal to 1440 (24 hours).\n\nAssuming `date` is the current date and `now` is the current time, the\nconditions which may lead to unexpected results are:\n\n* *incorrect time zone*: *date*'s time zone is not consistent with provided\n  *longitude*. Suitable values for *timezone* and *dst* should be provided. See\n  example at Novosibirsk in [example.py].\n\n* *Sun is up all day*: close to the poles, Sun never sets in summer/winter\n  time. For this dates, `is_daytime()` holds true for the whole `date`. Note\n  that the following holds true: `sunrise ≤ now < sunset`.\n\n* *Sun is down all day*: close to the poles, Sun never raises in summer/winter\n  time. For this dates, `is_nighttime()` holds true for the whole `date`.\n  Note that the following holds false: `sunrise < sunset`.\n\n* *Sun sets after midnight*: close to the poles, Sun may sets after 23:59. In\n  this case, `is_daytime()` and `is_nighttime()` behave as expected. The\n  following condition is true: `sunrise ≤ now ≤ 23:59 < sunset`.\n\n\n## Installation\n\nYou can simply copy the content of directory `suntime`. If only one\nimplementation is needed, the other can be deleted.\n\nAlternatively, MicroPython's tool `mip` can be exploited to install one\nimplementation or the whole library. As reference, choose one of the following\ncommands for installing the library on your Unix port:\n\n```sh\nmicropython -m mip install github:lorcap/micropython-suntime/sundatetime-package.json\nmicropython -m mip install github:lorcap/micropython-suntime/suntime-package.json\nmicropython -m mip install github:lorcap/micropython-suntime\n```\n\nSee MicroPython's [Package management](https://docs.micropython.org/en/latest/reference/packages.html)\nfor further details.\n\n\n## Examples of usage\n\n### Typical use case\n\nA typical use case for an embedded system is:\n\n```py\nimport datetime, time\nfrom suntime.sundatetime import Sundatetime\n\nclass Cet(datetime.timezone):\n    # See `datetime` documentation\n\n# initialization\nCET = Cet()\nRome = Sundatetime(42.5966460, 12.4360233)\nRome.calc_sunrise_sunset(datetime.datetime(2000, 1, 1, tzinfo=CET))\n\n# main loop (every minute or more)\nnow = datetime.datetime(*time.localtime()[:5], tzinfo=CET)\nif (now.date() > Rome.sunset.date()):\n    Rome.calc_sunrise_sunset(now)\nRome.is_daytime(now)\n```\n\n### Sunrise and sunset around the globe\n\nThe script provided in [example.py] shows sunrise and sunset time for several\nplaces and dates.\n\n\n[REFERENCES]: #\n\n[example.py]: example.py \"Script with examples\"\n"
}